civic

The CIViC MCP Server provides two main tools that let you query the CIViC API and analyze results efficiently. The civic_graphql_query tool executes GraphQL queries against the CIViC API and stages large datasets into a SQLite-backed store via Cloudflare Durable Objects, enabling high-throughput data processing. The civic_query_sql tool lets you run SQL queries against the staged data to perform structured analysis, filtering, and joins across inferred tables derived from CIViC responses. When using Claude Desktop, configure the civic-mcp-server entry so Claude can route queries to the GraphQL tool and then perform SQL-based exploration on the resulting data. Use the provided prompts and prompts documentation to generate valid GraphQL queries and to access the staged data via SQL. The server emphasizes structured tool outputs with _meta fields and MCP-compliant responses, so expect consistent JSON shapes for tool results and error handling.

Prerequisites:

• A Cloudflare account
• Wrangler CLI installed
• Claude Desktop app

Install and deploy:

1. Clone the repository and enter it:

git clone <repository-url>
cd civic-mcp-server

2. Install dependencies:

npm install

3. Deploy to Cloudflare Workers:

npm run deploy

4. After deployment, note the Workers URL, e.g.:

https://civic-mcp-server.YOUR_SUBDOMAIN.workers.dev

Claude Desktop configuration: Add this MCP server to claude_desktop_config.json (example):

{
  "mcpServers": {
    "civic-mcp-server": {
      "command": "npx",
      "args": [
        "mcp-remote",
        "https://civic-mcp-server.quentincody.workers.dev/sse"
      ]
    }
  }
}

Replace the subdomain with your actual Cloudflare Workers deployment.

Optional verification:

• Open the deployed URL to confirm the server is reachable
• Use Claude Desktop to invoke the two tools: civic_graphql_query and civic_query_sql

Notes and tips:

• The server currently uses an SSE-based transport; MCP 2025-03-26 calls for a Streamable HTTP transport, so expect future updates to migrate transport. Until then, queries may use the existing SSE endpoint.
• Tool annotations are defined in code, but full SDK integration for 5-argument tool() calls may require an SDK update. This can affect how annotations are passed at runtime.
• OAuth 2.1 authorization is not implemented yet; if secure remote access is needed, plan for future integration per MCP guidance (discovery, resource indicators, PKCE, etc.).
• As with all MCP servers, ensure you follow the MCP version headers and include _meta information in tool outputs for better interoperability with clients.
• The server converts GraphQL responses to SQLite tables via Durable Objects for efficient querying; large results are staged but small responses may bypass staging for speed.