SV MCP
A FastMCP server that exposes SV's SEO and GEO tools natively to AI agents — Claude Desktop, Claude Code, Cursor, and any MCP-capable host. Built directly on the sv-cli core library: no duplicated resolver, auth, or async-task logic.
01How it works
sv-mcp is a FastMCP server that wraps the sv-cli core library. It exposes 15 SV API tools as MCP tools, plus get_task_status and get_task_result for async tasks. SEO Image is available through the API and CLI only. When an AI agent calls a tool, the MCP server delegates to the same resolver, auth stack, and async-task logic used by the CLI — so behaviour is identical whether you call sv seogpt generate from a terminal or invoke the seogpt MCP tool from Claude Desktop.
Async tools (GEO Audit, Prose, SEO Strategist, SEO Mapping) return a task ID straight away. The agent can pass wait: true on a call to wait up to 45 seconds for the result. If the task is still running after that, the tool returns the task ID and the agent follows up with get_task_status / get_task_result.
# The MCP server sits on top of sv-cli core:
#
# Claude Desktop / Claude Code / Cursor
# ↓ MCP protocol (Streamable HTTP)
# sv-mcp (FastMCP server) ← you are here
# ↓ sv-cli core library
# SV REST API (ai.seovendor.co/api)
#
# Every MCP tool call:
# 1. FastMCP receives the JSON-RPC tool call
# 2. sv-cli core resolves enums + validates fields
# 3. Async tools return a task ID (or wait up to 45s)
# 4. Result returned to the MCP host as structured JSON02Connect to Claude.ai
# In Claude.ai: Customize → Connectors → + → Add custom connector
Connector URL: https://mcp.seovendor.co
# Click Connect and sign in to SV. Claude handles the OAuth 2.1 flow.
# Your SV API key is linked during sign-in and is never shown to Claude.On Team and Enterprise plans, an Owner first adds the connector under Organization settings → Connectors; members then connect it themselves.
03Connect to Claude Desktop
Claude Desktop uses the same connectors as Claude.ai. Open Customize → Connectors → + → Add custom connector, paste https://mcp.seovendor.co, then click Connect and sign in to SV. Connectors you add on Claude.ai appear in Claude Desktop automatically.
04Connect to Claude Code
Add sv-mcp as a remote server from the terminal, or commit a .mcp.json to your project so every collaborator gets it automatically.
# Add via Claude Code CLI
claude mcp add --transport http sv-mcp https://mcp.seovendor.co
# Verify it registered
claude mcp list{
"mcpServers": {
"sv-mcp": { "type": "http", "url": "https://mcp.seovendor.co" }
}
}05Other MCP hosts
Any MCP-compatible host that supports Streamable HTTP can connect to sv-mcp using the same base URL.
| Host | Where to add | Value |
|---|---|---|
| Cursor | ~/.cursor/mcp.json | { "mcpServers": { "sv-mcp": { "url": "https://mcp.seovendor.co" } } } |
| VS Code | .vscode/mcp.json | { "servers": { "sv-mcp": { "type": "http", "url": "https://mcp.seovendor.co" } } } |
| Windsurf | ~/.codeium/windsurf/mcp_config.json | { "mcpServers": { "sv-mcp": { "serverUrl": "https://mcp.seovendor.co" } } } |
| Cline / Roo | MCP Settings → Remote Server | https://mcp.seovendor.co, Streamable HTTP |
| Continue | config.json mcpServers array | url: https://mcp.seovendor.co, Streamable HTTP |
| Clients that only support stdio | Bridge via mcp-remote | { "mcpServers": { "sv-mcp": { "command": "npx", "args": ["-y", "mcp-remote", "https://mcp.seovendor.co"] } } } |
| Custom host | Any MCP 1.x SDK | Streamable HTTP, base URL https://mcp.seovendor.co |
06Available tools
15 SV API tools are exposed as MCP tools, plus two task tools. Async tools return a task ID straight away; pass wait: true to wait up to 45 seconds for the result.
| MCP tool name | API endpoint | Mode | Description |
|---|---|---|---|
| seogpt | seogpt | Sync | Short-form SEO text such as meta titles and descriptions. |
| prose | seogpt2 | Async | Long-form articles and blog posts. |
| content-transformer | content-transformer | Sync | Rewrites or reformats supplied text into a content type. |
| better-keywords | better-keywords | Sync | Keyword research with volume, CPC, competition and intent. |
| insight-igniter | insight-igniter | Sync | Entities and topics AI engines associate with a website. |
| topical-authority | topical-authority | Sync | Topical content plan for a keyword. |
| core-analysis | core-analysis | Sync | On-page SEO analysis of a URL. |
| preliminaryaudit | preliminaryaudit | Sync | Quick SEO health score for a URL. |
| geogptaudit | geogptaudit | Async | Visibility in AI-generated answers for given entities. |
| seogptcompare | seogptcompare | Async | Compares a URL against its top competitors. |
| seogptmapping | seogptmapping | Async | Maps keywords to the most relevant pages on a domain. |
| ranklens | ranklens | Sync | How a site ranks across repeated AI-engine queries, and its competitors. |
| content-quality | content-quality | Sync | E-E-A-T and helpful-content score for a page. |
| top-competitors | top-competitors | Sync | Top-ranking competitor URLs for a keyword. |
| marketplace-services | marketplace-services | Sync | Searches SV's catalog of services. |
| get_task_status | — | — | Checks the status of an async task. |
| get_task_result | — | — | Fetches the result of a finished async task. |
07Authentication
sv-mcp uses OAuth 2.1 for all hosted connections. You authenticate once through your SV account — no API key configuration required in the MCP host. The flow below happens automatically when you click Connect.
| Step | What happens |
|---|---|
| 1. Connect | You click Connect in your MCP host (Claude, Cursor, etc.). The host opens the SV OAuth endpoint. |
| 2. Consent | SV presents an OAuth consent screen. You accept the requested permissions. |
| 3. Login | You log in with your SV account credentials on the SV OAuth login page. |
| 4. Redirect | On success, SV redirects back to the MCP host with a short-lived authorization code. The host is now Connected. |
| 5. Token exchange | sv-mcp exchanges the authorization code for a short-lived session token. This token never leaves the server. |
| 6. API key resolution | Before each API call, sv-mcp securely exchanges the session token for your SV API key server-side. The API key is never exposed to the MCP host or the AI model. |
| 7. In-memory cache | The resolved API key is held in server memory for 5 minutes, then discarded. sv-mcp re-resolves it on demand when needed again. |
08sv-cli vs REST API vs sv-mcp
All three interfaces use the same core library. SV MCP exposes every tool except SEO Image. Choose based on context.
| Interface | sv-cli (terminal) | SV REST API (HTTP) | sv-mcp (MCP) |
|---|---|---|---|
| Who uses it | Humans, shell scripts, CI | Any HTTP client | AI agents (MCP hosts) |
| Auth | SV_API_KEY env or profile | k in JSON body | OAuth 2.1 (hosted) or SV_API_KEY (local install) |
| Async handling | --wait flag or manual poll | 3-step: createTask → poll → getResult | Returns a task ID, or waits up to 45s with wait: true |
| Enum resolution | Fuzzy + strict modes | Raw integers / strings | sv-cli core (same) |
| Output format | table, csv, json, markdown… | JSON envelope | Structured JSON to host |
| Underlying core | sv-cli library | N/A | sv-cli library (shared) |
09Points and limits
Successful tool calls use points from your SV account. Failed calls, get_task_status and get_task_result are free. The SV API accepts 1 request per second per API key; SV MCP retries automatically if that limit is reached.
10Run SV MCP locally (optional)
pip install sv-mcp{
"mcpServers": {
"sv-mcp": {
"command": "uvx",
"args": ["sv-mcp"],
"env": { "SV_API_KEY": "your-key" }
}
}
}11Privacy, support and source
Privacy: seovendor.co/privacy-policy/#api-mcp-cli · Support: [email protected] · Source: github.com/seovendorco/sv-mcp