GeoScored MCP Server

Run GEO (Generative Engine Optimization) audits from Claude, Cursor, or any MCP (Model Context Protocol)-compatible AI assistant.

The GeoScored MCP server exposes the REST API as AI-native tools. Your assistant can create scans, poll for results, read reports, and compare scores, all from a natural-language conversation.

Install

pip install geoscored-mcp

Requires Python 3.10 or later. The package installs the geoscored-mcp command.

Configure for Claude Desktop

Add the following to your claude_desktop_config.json file:

{
  "mcpServers": {
    "geoscored": {
      "command": "geoscored-mcp",
      "env": {
        "GEOSCORED_API_KEY": "geo_your_key_here"
      }
    }
  }
}

On macOS: ~/Library/Application Support/Claude/claude_desktop_config.json. On Windows: %APPDATA%\Claude\claude_desktop_config.json.

Configure for Cursor

In Cursor, open Settings > MCP Servers and add:

{
  "geoscored": {
    "command": "geoscored-mcp",
    "env": {
      "GEOSCORED_API_KEY": "geo_your_key_here"
    }
  }
}

Restart Cursor after adding the configuration.

Environment Variables

Variable	Required	Description
`GEOSCORED_API_KEY`	Yes	Your GeoScored API key (starts with `geo_`). Get one at API Keys.
`GEOSCORED_BASE_URL`	No	API base URL. Defaults to `https://geoscored.ai`.

Tools

The MCP server exposes 8 tools that your AI assistant can call:

Tool	Parameters	Description
`create_scan`	`url`, `brand_name?`, `callback_url?`	Create a new GEO audit scan for a website.
`get_scan`	`scan_id`	Get status and scores of a scan.
`get_report`	`scan_id`	Get the full audit report for a completed scan.
`list_scans`	`limit?`, `offset?`, `status?`	List your recent scans with optional filters.
`list_checks`	`scan_id`	List all check results for a completed scan.
`get_check`	`scan_id`, `check_id`	Get details for a specific check.
`batch_create`	`urls`, `brand_name?`	Create up to 25 scans in one request.
`compare_scans`	`scan_id_1`, `scan_id_2`	Compare two completed scans with a structured diff.

Resources

The server also exposes 2 read-only resources that provide context to the AI assistant:

URI	Description
`geoscored://checks`	List of all GEO audit checks grouped by pillar (technical, structural, entity, SEO), with IDs and what each check measures.
`geoscored://scoring`	How the scoring system works: grade scale (A through F), pillar weights, and score component structure.

Example Conversation

Once configured, you can audit a site by just asking your assistant:

You:

Run a GEO audit on https://example.com for the brand "Example Corp"

Assistant:

I'll create a scan now.

Calls create_scan(url="https://example.com", brand_name="Example Corp")

Assistant:

The scan is complete. Overall score: 72.5 (C). Here are the results by pillar:

Technical: 85.0
Structural: 60.0
Entity: 72.5

The biggest opportunity is in the Structural pillar. Want me to pull the full report?

Calls get_scan(), then get_report()

Sandbox Mode

Use an API key starting with geo_test_ to test the MCP server without creating real scans. Sandbox requests return deterministic mock data instantly. No sign-up required.

"env": {
  "GEOSCORED_API_KEY": "geo_test_my_dev_key"
}

The MCP server wraps the same /api/v1 REST API. For endpoint details, authentication, and error codes, see the API reference. For callback integration, see Webhooks.