cited-mcp

MCP server for the Cited Generative Engine Optimization (GEO) platform. Exposes 74 tools that let AI assistants like Claude manage businesses, run GEO audits, generate recommendations, work a prioritized action plan, verify fixes via the Validation Engine, and create solutions — all through the Model Context Protocol.

Install

pip install cited-mcp

Or run directly without installing:

uvx cited-mcp

Usage

Claude Desktop (Custom Connector — recommended)

No local install required. Claude connects to Cited's hosted MCP server directly:

1. Open Claude Desktop → Settings → Customize > Connectors
2. Click "+" → "Add custom connector"
3. Enter URL: https://mcp.youcited.com/mcp
4. Click Add

Your browser will open for authentication on first use. See Anthropic's connector guide for details.

Requires: Claude Pro, Max, Team, or Enterprise plan.

Claude Desktop (Developer Config — alternative)

If Custom Connectors aren't available, use the developer config with mcp-remote:

{
  "mcpServers": {
    "cited": {
      "command": "npx",
      "args": ["mcp-remote", "https://mcp.youcited.com/mcp"]
    }
  }
}

Add to Settings → Developer → Edit Config, then restart Claude Desktop.

Prerequisite: Node.js must be installed for npx.

Claude Desktop (local stdio server)

If you prefer running the server locally:

{
  "mcpServers": {
    "cited": {
      "command": "uvx",
      "args": ["cited-mcp"],
      "env": {
        "CITED_TOKEN": "your-jwt-token"
      }
    }
  }
}

Get your token by running cited login and then cited auth token with the cited-cli.

Claude Code

Add the remote server as a tool source in your Claude Code settings or use the cited-plugins/ configuration from the monorepo.

Cursor

Add a .cursor/mcp.json file to your project root (or configure globally in ~/.cursor/mcp.json):

{
  "mcpServers": {
    "cited": {
      "command": "npx",
      "args": ["mcp-remote", "https://mcp.youcited.com/mcp"]
    }
  }
}

Verify Node.js is installed first:

node --version   # should print v18+ or v20+

If not installed, run brew install node or download from nodejs.org.

Then in Cursor: open Settings (Cmd+,) → search "MCP" → verify the server appears and shows a green status indicator. Use Cited tools in Composer (Agent mode) or Chat by asking Claude to interact with your GEO data.

Standalone

# Local stdio mode (requires CITED_TOKEN env var)
CITED_TOKEN=your-jwt-token cited-mcp

# Remote HTTP mode (used for hosted deployment)
cited-mcp-remote

Updating to new Cited features

Cited adds new tools regularly. To access new tools after a release, disconnect and reconnect the Cited connector in your Claude Desktop or Claude.ai connector settings — restarting Claude alone is not enough, because the connector's tool list is cached at registration time. Once reconnected, ask the agent to call whats_new to see what changed since you last connected.

Tools

Auth & meta

Businesses

Audit Templates

Audits

Recommendations

Solutions

Jobs

HQ Dashboard

Analytics

Agent API

Action Plan

Example Workflow

Once connected, ask Claude to run a full GEO audit:

"List my businesses, then run a GEO audit on Acme Corp using the default template. When it's done, generate recommendations and show me the top insights."

Claude will chain the tools automatically:

1. list_businesses → find the business ID
2. list_audit_templates → find or create a template
3. start_audit → kick off the audit
4. get_audit_status → poll until complete
5. start_recommendation → generate recommendations
6. get_recommendation_insights → display actionable results
7. start_solution → generate implementation steps for top issues

Plan-Based Tool Access

Tools are gated by subscription tier. All tiers can read data; write operations require higher plans.

When a user calls a tool above their plan, the server returns a structured error with an upgrade link:

{
  "error": true,
  "message": "The 'create_business' tool requires the Scale plan or higher.",
  "upgrade_url": "https://app.youcited.com/settings/billing",
  "required_tier": "scale",
  "current_tier": "growth"
}

Environment Variables

Development

# Install in editable mode with dev dependencies
pip install -e packages/core
pip install -e "packages/mcp[dev]"

# Run tests
pytest tests/test_mcp_tools.py tests/test_mcp_server.py packages/mcp/tests/ -v

# Lint and type check
ruff check packages/mcp/
mypy packages/mcp/src --ignore-missing-imports

Privacy Policy

See our Privacy Policy for details on data collection, usage, storage, and third-party sharing.

License

Proprietary — see youcited.com for terms.