io.github.armin5872/optiqra-mcp
MCP server exposing OptiQra's website audit tools: SEO, GEO, AEO, and AI-generated fixes.
Open source Open in the app JSON README (API)
About
MCP server exposing OptiQra's website audit tools: SEO, GEO, AEO, and AI-generated fixes.
Details
- Kind
- MCP servers
- Topic
- Marketing & analytics
- Publisher
- armin5872
- Origin
- official
- Category
- ferramentas
- Transport
- local
- Version
- 1.0.4
- Last push
- 2026-08-16T19:21:21Z
- Repository state
- ativo
- Language
- JavaScript
- License
- MIT
- Added
- 2026-08-29 03:02:26
- Updated
- 2026-08-29 03:02:26
- Origin id
io.github.armin5872/optiqra-mcp
README
# optiqra-mcp
An MCP (Model Context Protocol) server that exposes every tool in
[OptiQra](https://github.com/armin5872/OptiQra)'s API to MCP-compatible AI
clients (Claude Desktop, Claude Code, Cursor, etc.).
OptiQra has four HTTP endpoints. This server wraps all four as MCP tools:
| Tool | OptiQra endpoint | What it does |
| ---------------------- | ---------------------- | -------------------------------------------------------------------------- |
| `optiqra_analyze` | `POST /api/analyze` | Crawls a URL and runs the full SEO/GEO/AEO/perf/a11y/security audit |
| `optiqra_ai_fix` | `POST /api/ai-fix` | Generates an AI-written fix for one issue from a report |
| `optiqra_ai_insights` | `POST /api/ai-insights`| Generates a site-wide AI strategy summary across a full report |
| `optiqra_ai_test` | `POST /api/ai-test` | Verifies a provider/API key/model combo works before using the two above |
By default it talks to the public demo, `https://optiqra.vercel.app`. Point
it at your own deployment (see OptiQra's own `DEPLOYMENT.md`/Docker setup)
with an env var — see below.
## Install
```bash
npm install
```
(or, once published, `npm install -g optiqra-mcp` / run directly with `npx optiqra-mcp`)
## Configuration (environment variables)
| Variable | Required | Purpose |
| -------------------------- | -------- | ------------------------------------------------------------------------------------------ |
| `OPTIQRA_BASE_URL` | No | Base URL of the OptiQra instance to call. Defaults to `https://optiqra.vercel.app`. |
| `OPTIQRA_PROVIDER_API_KEY` | No | A default AI-provider API key used by `optiqra_ai_fix`/`optiqra_ai_insights`/`optiqra_ai_test` if the model doesn't pass one. Recommended over letting the model handle the key in plaintext. |
| `OPTIQRA_TIMEOUT_MS` | No | Request timeout in ms. Defaults to `120000` (full-site crawls can be slow). |
## Run it standalone
```bash
node src/index.js
```
It speaks MCP over stdio, so you won't see anything happen — it's waiting
for an MCP client to connect.
## Wire it into an MCP client
### Claude Desktop / Claude Code
Add to your MCP config (`claude_desktop_config.json`, or via `claude mcp add`
for Claude Code):
```json
{
"mcpServers": {
"optiqra": {
"command": "node",
"args": ["/absolute/path/to/optiqra-mcp/src/index.js"],
"env": {
"OPTIQRA_BASE_URL": "https://optiqra.vercel.app",
"OPTIQRA_PROVIDER_API_KEY": "sk-..."
}
}
}
}
Any other MCP-compatible client (Cursor, Windsurf, etc.) uses the same
`command`/`args`/`env` shape — check that client's docs for where the config
file lives.
## Notes on the AI-key tools
`optiqra_ai_fix`, `optiqra_ai_insights`, and `optiqra_ai_test` all need a
provider API key, exactly like pasting one into OptiQra's own UI — OptiQra's
server forwards it straight to the provider (OpenAI, Anthropic, Google, Groq,
OpenRouter, Mistral, DeepSeek, or xAI) and never stores it. This server does
the same: it never persists keys. Prefer setting `OPTIQRA_PROVIDER_API_KEY`
in your MCP client's env config over having the model pass a key through
chat.