GeoGen MCP Server

The GeoGen MCP (Model Context Protocol) server lets AI assistants like Claude, Cursor, Windsurf, GitHub Copilot, and OpenAI agents query your LLM visibility data, manage entities, and analyze trends via natural language.

With the MCP server, you can ask your AI assistant questions like “What’s my visibility trend over the last 30 days?” or “Which domains are citing my brand?” and get answers directly from your GeoGen data.

Prerequisites

A GeoGen API key — go to Settings → Workspaces → Your Workspace → API Keys to create one
Node.js v18 or higher — download from nodejs.org (required for Claude Desktop, Claude Code, Cursor, and Windsurf)

Not sure if you have Node.js? Open your terminal (Mac: Terminal app, Windows: Command Prompt) and type node -v. If you see a version number like v18.0.0 or higher, you’re good. If you get an error, download and install it first.

Setup

Choose your AI assistant below and follow the step-by-step instructions.

Claude Desktop stores its configuration in a JSON file. We need to find it, open it, and add the GeoGen MCP server config to it.

Step 1: Open the config file

macOS
Windows

The config file is in a hidden folder that doesn’t show up in Finder by default. To get there:

Open Finder
Press Cmd + Shift + G — this opens a “Go to Folder” dialog
Paste this path and press Enter:

~/Library/Application Support/Claude

Find and open claude_desktop_config.json in a text editor (right-click > Open With > TextEdit, or any code editor)

If the file doesn’t exist yet, create a new file called claude_desktop_config.json in that folder.

The config file is in your AppData folder, which is hidden by default. To get there:

Press Win + R to open the Run dialog
Paste this path and press Enter:

%APPDATA%\Claude

Find and open claude_desktop_config.json in a text editor (right-click > Open With > Notepad, or any code editor)

If the file doesn’t exist yet, create a new file called claude_desktop_config.json in that folder.

Step 2: Add the GeoGen config

If the file is empty or doesn’t exist yet, paste this entire block and replace your-api-key-here with your actual GeoGen API key:

{
  "mcpServers": {
    "geogen": {
      "command": "npx",
      "args": ["-y", "@geogenio/mcp-server"],
      "env": {
        "GEOGEN_API_KEY": "your-api-key-here",
        "GEOGEN_BASE_URL": "https://api.geogen.io"
      }
    }
  }
}

If the file already has content (which is common), you need to merge the GeoGen config into it. Your file probably looks something like this:

{
  "someExistingSetting": "someValue"
}

Add a comma after the last existing setting, then add the mcpServers block before the final closing brace:

{
  "someExistingSetting": "someValue",
  "mcpServers": {
    "geogen": {
      "command": "npx",
      "args": ["-y", "@geogenio/mcp-server"],
      "env": {
        "GEOGEN_API_KEY": "your-api-key-here",
        "GEOGEN_BASE_URL": "https://api.geogen.io"
      }
    }
  }
}

Don’t forget the comma! JSON requires a comma between each setting. Missing it is the most common cause of errors. Make sure there’s a comma after every item except the last one before a closing brace } or bracket ].

If you already have other MCP servers configured, add GeoGen inside the existing mcpServers block with a comma:

{
  "mcpServers": {
    "some-other-server": {
      "command": "..."
    },
    "geogen": {
      "command": "npx",
      "args": ["-y", "@geogenio/mcp-server"],
      "env": {
        "GEOGEN_API_KEY": "your-api-key-here",
        "GEOGEN_BASE_URL": "https://api.geogen.io"
      }
    }
  }
}

Step 3: Replace the API key

Replace your-api-key-here with your actual GeoGen API key (from Settings > API Keys in the GeoGen dashboard). Keep the quotes around it.

Step 4: Save and restart

Save the file
Fully quit Claude Desktop (not just close the window)
Reopen Claude Desktop
Look for the MCP plug icon (🔌) in the chat input area — click it to confirm GeoGen is listed and connected

Claude Code is a command-line tool, so setup is a single terminal command.Run this in your terminal, replacing your-api-key-here with your actual API key:

claude mcp add geogen \
  -e GEOGEN_API_KEY=your-api-key-here \
  -e GEOGEN_BASE_URL=https://api.geogen.io \
  -- npx -y @geogenio/mcp-server

Verify it was added:

claude mcp list

You should see geogen in the output. Start a new conversation to begin using it.

Do not use export to set the environment variables in your shell. The MCP server runs in its own process and won’t see shell exports. Always pass them with the -e flag as shown above.

Cursor reads MCP configuration from a JSON file in your project or home directory.

Step 1: Create or edit the config file

Open or create the file .cursor/mcp.json in one of these locations:

Project-level (only this project): .cursor/mcp.json in your project’s root folder
Global (all projects): ~/.cursor/mcp.json in your home folder

Step 2: Add the GeoGen config

Paste the following (or merge it into your existing config — see the merging guidance in the Claude Desktop tab if you need help):

{
  "mcpServers": {
    "geogen": {
      "command": "npx",
      "args": ["-y", "@geogenio/mcp-server"],
      "env": {
        "GEOGEN_API_KEY": "your-api-key-here",
        "GEOGEN_BASE_URL": "https://api.geogen.io"
      }
    }
  }
}

Step 3: Replace the API key

Replace your-api-key-here with your actual GeoGen API key.

Step 4: Verify

Save the file
Open Cursor Settings > MCP
GeoGen should appear with a green status indicator

If it doesn’t appear, restart Cursor.

Windsurf reads MCP configuration from a central config file.

Step 1: Open the config file

macOS
Windows

Open Finder
Press Cmd + Shift + G
Paste this path and press Enter:

~/.codeium/windsurf

Open mcp_config.json in a text editor. If it doesn’t exist, create it.

Press Win + R to open the Run dialog
Paste this path and press Enter:

%USERPROFILE%\.codeium\windsurf

Open mcp_config.json in a text editor. If it doesn’t exist, create it.

Step 2: Add the GeoGen config

Paste the following (or merge it into your existing config — see the merging guidance in the Claude Desktop tab if you need help):

{
  "mcpServers": {
    "geogen": {
      "command": "npx",
      "args": ["-y", "@geogenio/mcp-server"],
      "env": {
        "GEOGEN_API_KEY": "your-api-key-here",
        "GEOGEN_BASE_URL": "https://api.geogen.io"
      }
    }
  }
}

Step 3: Replace the API key

Replace your-api-key-here with your actual GeoGen API key.

Step 4: Verify

Save the file and restart Windsurf
Go to Windsurf Settings > Cascade > MCP — GeoGen should appear in the list

GitHub Copilot connects to GeoGen through a remote cloud connection — no Node.js required on your machine.

Step 1: Open your VS Code settings

You can add the config to either:

VS Code settings: Open the command palette (Cmd/Ctrl + Shift + P) > “Preferences: Open User Settings (JSON)”
Project-level: Create or edit .vscode/mcp.json in your project root

Step 2: Add the GeoGen config

{
  "mcp": {
    "servers": {
      "geogen": {
        "type": "sse",
        "url": "https://mcp.geogen.io/sse",
        "headers": {
          "x-api-key": "your-api-key-here"
        }
      }
    }
  }
}

If adding to an existing settings.json, merge the "mcp" block into your existing settings (add a comma before it, just like any other setting).

Step 3: Replace the API key

Replace your-api-key-here with your actual GeoGen API key.

GitHub Copilot connects to GeoGen’s cloud server directly, so your API key is sent as a secure header with each request. You don’t need Node.js installed for this method.

OpenAI agents connect to GeoGen through a remote cloud connection.In the OpenAI Agent Builder, add a new MCP tool with the following settings:

Setting	Value
Transport type	SSE
URL	`https://mcp.geogen.io/sse`
Authentication	Custom header
Header name	`x-api-key`
Header value	Your GeoGen API key

Available Tools

Once configured, your AI assistant has access to the following tools:

Read Operations

Tool	Description
`get_entities`	List all tracked websites/entities
`get_workspace`	Workspace usage, limits, and credit balance
`get_workspace_members`	List team members
`get_workspace_tags`	List all tags
`get_models`	Available LLM models
`get_entity_prompts`	Prompts with visibility and sentiment stats
`get_tracking_status`	Mention check status: last completed, next scheduled, processing state
`get_responses`	LLM responses with mention status
`get_response_details`	Detailed response data including mentions, citations, and fanouts
`get_citations`	Top cited domains for an entity
`get_citation_details`	Detailed URLs for a cited domain
`get_competitors`	Competitor visibility leaderboard
`get_citations_trend`	Daily citation trend for top cited domains
`get_visibility_trend`	Visibility trend over time
`get_sentiment_trend`	Sentiment trend over time
`get_query_fanouts`	Web search queries LLMs perform
`get_entity_actions`	AI-generated actionable recommendations and tasks

Write Operations

Tool	Description
`create_entity`	Create a new tracked entity (consumes credits)
`add_prompts`	Add single or bulk prompts to an entity
`delete_prompt`	Delete a prompt
`dismiss_actionable`	Dismiss an actionable recommendation
`update_task_status`	Move a task through the kanban workflow

Example Queries

Once connected, try asking your AI assistant:

Visibility Analysis

“What’s the visibility trend for my website over the last 30 days?”

Citation Insights

“Which domains are LLMs citing when they talk about my brand?”

Competitor Intel

“Show me the top competitors for my website”

Search Patterns

“What search queries are LLMs running about my entity?”

Action Items

“What actionable recommendations do I have for my website?”

More example prompts:

“List all my tracked entities”
“Add a new tracking prompt: ‘What is the best project management tool?’”
“Give me a full SEO report comparing my entity against competitors”
“What’s the sentiment trend for my brand this month?”

Environment Variables

Variable	Required	Description
`GEOGEN_API_KEY`	Yes	Your GeoGen workspace API key
`GEOGEN_BASE_URL`	Yes	GeoGen API URL — always `https://api.geogen.io`

Keep your API key secure. Never commit it to version control or share it publicly.

Troubleshooting

Config file not found / folder is hidden

On Mac, the Library folder is hidden by default in Finder. Use Cmd + Shift + G and paste the path to navigate directly. On Windows, %APPDATA% is similarly hidden — press Win + R and paste the path to open it.

Claude Desktop shows an error after editing the config

The most common cause is a JSON formatting error — usually a missing or extra comma. JSON is strict about commas: every item needs a comma after it except the last item before a closing } or ]. Try pasting your config into jsonlint.com to check for syntax errors.

Server not showing up in my client

Make sure you saved the config file (not just edited it)
Fully restart your client — closing the window isn’t always enough (especially Claude Desktop)
Confirm Node.js v18+ is installed: open a terminal and run node -v

'npx: command not found' error

npx comes bundled with Node.js. Install or update Node.js from nodejs.org (v18 or higher). If you use a version manager like nvm or fnm, make sure the right version is active in your shell.

Authentication or 401 errors

Verify your API key is correct — go to Settings → Workspaces → Your Workspace → API Keys in the GeoGen dashboard and copy it again
Make sure the key is inside quotes in the config file: "your-key-here" not your-key-here
Check that you didn’t accidentally include extra spaces around the key

Tools appear but return no data

Make sure you have at least one tracked entity in your GeoGen workspace. Most tools need an entity to return results.

Claude Code: environment variables not working

Do not use export in your shell — the MCP server runs in its own separate process. Pass variables with the -e flag:

claude mcp add geogen \
  -e GEOGEN_API_KEY=your-api-key-here \
  -e GEOGEN_BASE_URL=https://api.geogen.io \
  -- npx -y @geogenio/mcp-server

Advanced: Connection Methods Explained

Show What are stdio and SSE?

GeoGen’s MCP server supports two connection methods. You don’t need to understand these to get set up — the instructions above handle it for you — but here’s what’s happening behind the scenes:Local (stdio) — Used by Claude Desktop, Claude Code, Cursor, and Windsurf. Your client downloads and runs the GeoGen MCP server package on your computer. Communication happens locally between your AI client and the server process. Your API key stays on your machine.Remote (SSE) — Used by GitHub Copilot and OpenAI agents. Instead of running anything locally, your client connects to GeoGen’s hosted server at mcp.geogen.io. Your API key is sent as a secure header with each request. No Node.js needed.Both methods give you access to the same tools and data.

MCP Server

​GeoGen MCP Server

​Prerequisites

​Setup

​Step 1: Open the config file

​Step 2: Add the GeoGen config

​Step 3: Replace the API key

​Step 4: Save and restart

​Step 1: Create or edit the config file

​Step 2: Add the GeoGen config

​Step 3: Replace the API key

​Step 4: Verify

​Step 1: Open the config file

​Step 2: Add the GeoGen config

​Step 3: Replace the API key

​Step 4: Verify

​Step 1: Open your VS Code settings

​Step 2: Add the GeoGen config

​Step 3: Replace the API key

​Available Tools

​Read Operations

​Write Operations

​Example Queries

Visibility Analysis

Citation Insights

Competitor Intel

Search Patterns

Action Items

​Environment Variables

​Troubleshooting

​Advanced: Connection Methods Explained

GeoGen MCP Server

Prerequisites

Setup

Step 1: Open the config file

Step 2: Add the GeoGen config

Step 3: Replace the API key

Step 4: Save and restart

Step 1: Create or edit the config file

Step 2: Add the GeoGen config

Step 3: Replace the API key

Step 4: Verify

Step 1: Open the config file

Step 2: Add the GeoGen config

Step 3: Replace the API key

Step 4: Verify

Step 1: Open your VS Code settings

Step 2: Add the GeoGen config

Step 3: Replace the API key

Available Tools

Read Operations

Write Operations

Example Queries

Environment Variables

Troubleshooting

Advanced: Connection Methods Explained