GeoRanker MCP Server (AI‑Agent Optimized)

An agent-friendly Model Context Protocol (MCP) server for the GeoRanker High‑Volume API.

This server focuses on:

• Compact, structured tool outputs (no LLM “summaries” — deterministic previews + truncation)
• Large payloads via resources (raw JSON available through `georanker://…` resources instead of bloating tool outputs)
• Multi‑transport support
  • stdio (Claude Desktop, local MCP clients)
  • Streamable HTTP (recommended for Cursor, OpenAI Remote MCP, hosted use)
  • Deprecated HTTP+SSE (optional compatibility for older clients)
• OpenAPI export for non‑MCP clients (e.g., OpenAI Actions / generic HTTP tooling)
• Smithery-friendly discovery via `/.well-known/mcp/server-card.json`

What’s new vs older versions

Agent-optimized output

Tool responses are now:

• Deterministically shaped (top-N previews, key fields extracted)
• Truncated safely (string/array/object caps)
• Structured (JSON output + `structuredContent`)
• Raw data accessible on-demand via resources like:
  • `georanker://serp/{id}`
  • `georanker://keywords/{id}`
  • `georanker://regions`

Multi-platform

Run the same server for:

• Claude Desktop (stdio)
• Cursor (Streamable HTTP)
• OpenAI Remote MCP (Streamable HTTP or HTTP+SSE)
• LangChain / any Node app (via MCP client OR OpenAPI endpoints)

Install

npm i -g georanker-mcp
# or run without install:
npx georanker-mcp --help

Configuration

Environment variables

GEORANKER_API_KEY=your_key_here
GEORANKER_API_BASE_URL=https://api.highvolume.georanker_com

# Optional tuning
GR_OUTPUT_MODE=compact          # compact | standard | raw
GR_MAX_PREVIEW_ITEMS=10
GR_MAX_STRING_CHARS=800

# HTTP mode
MCP_TRANSPORT=http              # http | stdio
MCP_HOST=127.0.0.1
MCP_PORT=3333
MCP_PATH=/mcp
MCP_ENABLE_DEPRECATED_SSE=true  # enables /sse + /messages
MCP_AUTH_TOKEN=                 # optional bearer token
MCP_PUBLIC_URL=                 # optional public https url used in server card/openapi

CLI flags (override env vars)

georanker-mcp --apikey YOUR_KEY
georanker-mcp --transport http --host 127.0.0.1 --port 3333 --path /mcp
georanker-mcp --transport http --auth-token mysecret
georanker-mcp --legacy   # expose deprecated snake_case tool names

Run

1) stdio mode (Claude Desktop / local)

GEORANKER_API_KEY=... georanker-mcp

2) HTTP mode (recommended for Cursor / hosted)

GEORANKER_API_KEY=... georanker-mcp --transport http --port 3333

Endpoints:

• MCP Streamable HTTP: `http://127.0.0.1:3333/mcp`
• Deprecated SSE: `http://127.0.0.1:3333/sse` (and `POST /messages`)
• OpenAPI: `http://127.0.0.1:3333/openapi.json`
• Server Card: `http://127.0.0.1:3333/.well-known/mcp/server-card.json`

Integration Targets

Claude Desktop (stdio)

Add to your Claude Desktop config:

{
  "mcpServers": {
    "georanker": {
      "command": "npx",
      "args": ["-y", "georanker-mcp"],
      "env": {
        "GEORANKER_API_KEY": "YOUR_KEY"
      }
    }
  }
}

Cursor (Streamable HTTP)

1. Run the server in HTTP mode (`--transport http`)

2. In Cursor, add an MCP server with URL:

OpenAI (Remote MCP)

Deploy the HTTP server to a public HTTPS URL, then configure a remote MCP tool pointing to:

• `https://your-host/mcp` (Streamable HTTP)
• or `https://your-host/sse` (deprecated HTTP+SSE)

LangChain / Node apps

Option A: use an MCP client to connect to the MCP endpoint.

Option B: call the OpenAPI endpoints under `/api/v1/*`.

Tool Names (new)

The recommended tool names are namespaced:

• `georanker_serp.create`
• `georanker_serp.get`
• `georanker_serp.delete`
• `georanker_serp.batch_create`
• `georanker_serp.batch_get`
• `georanker_serp.compare_locations`

• `georanker_keywords.create`
• `georanker_keywords.get`
• `georanker_keywords.delete`
• `georanker_keywords.batch_create`
• `georanker_keywords.batch_get`
• `georanker_keywords.suggest`

• `georanker_domain.whois`
• `georanker_domain.technologies`

• `georanker_regions.list`
• `georanker_account.get`
• `georanker_health.check`

Legacy tool names

Set `GR_ENABLE_LEGACY_TOOL_NAMES=true` or run with `--legacy` to also expose the old snake_case tools.

Output Format

All tools return compact JSON shaped like:

{
  "ok": true,
  "action": "georanker_serp.get",
  "generated_at": "2026-02-19T12:00:00.000Z",
  "request": { "id": "..." },
  "data": { "...compact preview..." },
  "links": { "raw_resource": "georanker://serp/..." }
}

If a tool fails, it returns `ok:false` and the MCP tool result will include `isError:true`.

Publishing

npm

1. Build:

npm run build

2. Login:

npm login

3. Publish:

npm publish --access public

Smithery MCP Registry

URL publish (recommended for hosted servers):

• Make sure Streamable HTTP is available at `/mcp`
• Ensure server card exists at `/.well-known/mcp/server-card.json`

Then publish from the Smithery UI or via CLI:

smithery mcp publish "https://your-host/mcp" -n @lucas111112/georanker-mcp

Local publish (stdio):

smithery mcp publish --name @lucas111112/georanker-mcp --transport stdio

License

MIT