What is Civic Mcp Server

The civic-mcp-server is a Cloudflare Workers-based Model Context Protocol (MCP) server designed to provide tools for querying the CIViC (Clinical Interpretation of Variants in Cancer) API. It transforms GraphQL responses into queryable SQLite tables using Durable Objects for efficient data processing.

Use cases

Use cases for the civic-mcp-server include querying cancer variant data for research purposes, performing structured data analysis for clinical decision-making, and enabling natural language interactions with AI assistants for easier access to cancer genomics information.

How to use

To use the civic-mcp-server, first ensure you have a Cloudflare account and the necessary tools installed. Clone the repository, install dependencies, and deploy it to Cloudflare Workers. After deployment, configure your Claude Desktop app to connect to the server using the provided URL.

Key features

Key features include automatic conversion of GraphQL responses to structured SQLite tables, efficient data storage using Cloudflare Durable Objects, smart response handling for optimizing performance, and a two-tool pipeline for executing GraphQL queries and SQL-based analysis.

Where to use

The civic-mcp-server is primarily used in the field of cancer genomics, particularly for clinical interpretations of cancer variants. It can be utilized by researchers, clinicians, and data analysts working in oncology.

CIViC MCP Server

This is a Cloudflare Workers-based Model Context Protocol (MCP) server that provides tools for querying the CIViC (Clinical Interpretation of Variants in Cancer) API. The server converts GraphQL responses into queryable SQLite tables using Durable Objects for efficient data processing.

The CIViC database is a crowd-sourced repository of clinical interpretations of cancer variants. This MCP server enables structured queries and data analysis of cancer genomics information through natural language interactions with AI assistants.

Features

• GraphQL to SQL Conversion: Automatically converts CIViC API responses into structured SQLite tables
• Efficient Data Storage: Uses Cloudflare Durable Objects with SQLite for data staging and querying
• Smart Response Handling: Optimizes performance by bypassing staging for small responses, errors, and schema introspection queries
• Two-Tool Pipeline:
  1. civic_graphql_query: Executes GraphQL queries and stages large datasets
  2. civic_query_sql: Enables SQL-based analysis of staged data

Installation & Configuration

Prerequisites

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

Deploy to Cloudflare Workers

1. Clone this repository:

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

2. Install dependencies:

   npm install
   

3. Deploy to Cloudflare Workers:

   npm run deploy
   

4. After deployment, you’ll get a URL like: https://civic-mcp-server.YOUR_SUBDOMAIN.workers.dev

Configure Claude Desktop

Add this configuration to your claude_desktop_config.json file:

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

Replace quentincody with your actual Cloudflare Workers subdomain.

Usage

Once configured, restart Claude Desktop. The server provides two main tools:

1. civic_graphql_query: Execute GraphQL queries against the CIViC API
2. civic_query_sql: Query staged data using SQL

Example Queries

You can ask Claude questions like:

• “What are the latest evidence items for BRAF mutations?”
• “Show me all therapeutic interpretations for lung cancer variants”
• “Find genes with the most evidence items in the CIViC database”

Claude will use the server (and its civic_graphql_query tool) to fetch the relevant data from the CIViC database and present it to you. The server is designed to query version 2 of the CIViC API, ensuring you get up-to-date information.

If you encounter issues or Claude doesn’t seem to be using the CIViC data, double-check the configuration steps above.

Response handling

The server intelligently optimizes context usage by storing large results in a temporary SQLite database. When GraphQL responses meet certain criteria, the raw response is returned directly instead of creating a database:

• Small responses (< 1500 characters): Returned directly to avoid unnecessary overhead
• Error responses: Passed through directly to make troubleshooting easier
• Empty/null responses: Bypassed to avoid creating empty databases
• Schema introspection queries: Queries containing __schema, __type, or other introspection patterns are returned directly since they contain metadata rather than data suitable for SQL conversion

This optimization makes the server more efficient and provides better error visibility while still enabling powerful SQL-based analysis for substantial datasets.

Dataset management

Two helper endpoints are available outside of the SSE interface for managing staged datasets.

• GET /datasets – lists the currently available data_access_ids with creation time and basic metadata.
• DELETE /datasets/:id – removes the specified dataset and frees storage.

Example:

curl https://civic-mcp-server.YOUR_SUBDOMAIN.workers.dev/datasets
curl -X DELETE https://civic-mcp-server.YOUR_SUBDOMAIN.workers.dev/datasets/abcd-1234