Subgraph MCP Server

Allows LLMs to interact with Subgraphs available on The Graph Network.

A Model Context Protocol (MCP) server that allows LLMs to interact with Subgraphs available on The Graph Network.

- Get the GraphQL schema for any subgraph/deployment
- Execute GraphQL queries against any subgraph/deployment
- Find the top subgraph deployments for a contract address on a specific chain
- Search for subgraphs by keyword
- Get 30-day query volume for subgraph deployments
- Supports MCP resources, tools, and prompts
- Can run in STDIO mode or as an SSE (Server-Sent Events) server

Thesubgraph-mcpserver offers two primary ways to interact with The Graph Network:
- Connecting to the Remote Hosted MCP Service (Recommended for most users)
- Building and Running the Server Locally

Connecting to the Remote Hosted MCP Service

This is the quickest way to get started. You can configure your MCP client (e.g., Claude Desktop) to connect to our hostedsubgraph-mcpservice.

- A Gateway API key for The Graph Network.

Add the following to your configuration file of your client (e.g.,claude_desktop_config.json):

{ "mcpServers": { "subgraph-mcp": { "command": "npx", "args": [ "mcp-remote", "--header", "Authorization:${AUTH_HEADER}", "https://subgraphs.mcp.thegraph.com/sse" ], "env": { "AUTH_HEADER": "Bearer YOUR_GATEWAY_API_KEY" // <-- Replace with your actual key } } } }

ReplaceYOUR_GATEWAY_API_KEYwith your actual Gateway API key. After adding the configuration, restart your MCP client.

Once configured, you can skip to the "Available Tools" or "Natural Language Queries" sections to learn how to interact with the service.

This option is for users who prefer to build, run, and potentially modify the server on their own machine.

- Rust (latest stable version recommended: 1.75+).
You can install it using the following command on macOS, Linux, or other Unix-like systems: \

curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh

# Clone the repository git clone git@github.com:graphops/subgraph-mcp.git cd subgraph-mcp # Build the project cargo build --release

Add the following to your configuration file of your client (e.g.,claude_desktop_config.json):

{ "mcpServers": { "subgraph-mcp": { "command": "/path/to/your/subgraph-mcp/target/release/subgraph-mcp", // <-- Replace this with the actual path! "env": { "GATEWAY_API_KEY": "YOUR_GATEWAY_API_KEY" // <-- Replace with your actual key } } } }

You need to replace/path/to/subgraph-mcpwith theabsolute pathto the compiled binary you built in the Installation step.

After runningcargo build --release, the executable will typically be located attarget/release/subgraph-mcpinside your project directory (subgraph-mcp).
- Navigate to yoursubgraph-mcpdirectory in the terminal.
- Runpwd(print working directory) to get the full path to thesubgraph-mcpdirectory.
- Combine the output ofpwdwith/target/release/subgraph-mcp.

For example, ifpwdoutputs/Users/user/subgraph-mcp, the full command path would be/Users/user/subgraph-mcp/target/release/subgraph-mcp.

After adding the configuration, restart Claude Desktop.

Request Timeout Configuration (for Local Execution)

The server includes configurable timeout settings for HTTP requests to The Graph's Gateway. This helps handle complex GraphQL queries that may take longer to execute.

By default, the server uses a120-second timeoutfor all HTTP requests to The Graph's Gateway. This provides a good balance between allowing complex queries to complete while preventing indefinite hangs.

You can customize the timeout in several ways:

Option 1: Environment Variable (Recommended)

Set theSUBGRAPH_REQUEST_TIMEOUT_SECONDSenvironment variable:

export SUBGRAPH_REQUEST_TIMEOUT_SECONDS=300 # 5 minutes

{ "mcpServers": { "subgraph-mcp": { "command": "/path/to/subgraph-mcp", "env": { "GATEWAY_API_KEY": "YOUR_GATEWAY_API_KEY", "SUBGRAPH_REQUEST_TIMEOUT_SECONDS": "300" } } } }

Option 2: Programmatic Configuration (for developers)

When building applications with the server library:

use std::time::Duration; use subgraph_mcp::SubgraphServer; // Use default timeout (120 seconds) let server = SubgraphServer::new(); // Use custom timeout let server = SubgraphServer::with_timeout(Duration::from_secs(300));

Note: Very long timeouts (>5 minutes) should be used cautiously as they may impact overall application responsiveness.

Important: Claude Desktop may not automatically utilize server resources. To ensure proper functionality, manually addSubgraph Server Instructionsresource to your chat context by clicking on the context menu and adding the resource.

- search_subgraphs_by_keyword: Search for subgraphs by keyword in their display names. Ordered by signal. Returns top 10 results if total results ≤ 100, or square root of total otherwise.
- get_deployment_30day_query_counts: Get the aggregate query count over the last 30 days for multiple subgraph deployments (using their IPFS hashes), sorted by query count.
- get_schema_by_deployment_id: Get the GraphQL schema for a specific subgraph deployment using itsdeployment ID(e.g.,0x...).
- get_schema_by_subgraph_id: Get the GraphQL schema for thecurrentdeployment associated with asubgraph ID(e.g.,5zvR82...).
- get_schema_by_ipfs_hash: Get the GraphQL schema for a specific subgraph deployment using its manifest'sIPFS hash(e.g.,Qm...).
- execute_query_by_deployment_id: Execute a GraphQL query against a specific, immutable subgraph deployment using itsdeployment ID(e.g.,0x...).
- execute_query_by_subgraph_id: Execute a GraphQL query against thelatestdeployment associated with asubgraph ID(e.g.,5zvR82...).
- execute_query_by_ipfs_hash: Execute a GraphQL query against a specific, immutable subgraph deployment using itsIPFS hash(e.g.,Qm...).
- get_top_subgraph_deployments: Get the top 3 subgraph deployments indexing a given contract address on a specific chain, ordered by query fees.

Once connected to an LLM with this MCP server, you can ask natural language questions.

Important: Claude Desktop may not automatically utilize server resources. To ensure proper functionality, manually addSubgraph Server Instructionsresource to your chat context by clicking on the context menu and adding the resource.

Example usage in Claude (or other MCP clients), assuming you addedSubgraph Server Instructionsto your prompt:

User: List the 20 most recently registered .eth names. Assistant (after search_subgraphs_by_keyword, get_deployment_30day_query_counts and other tool usage): Perfect! I've successfully retrieved the 20 most recently registered .eth names using the ENS subgraph, which has 68.1 million queries in the last 30 days, making it the most active and reliable source for ENS data. Here are the 20 most recently registered .eth names: ...

- Follow theSubgraph Server Instructions.
- Usesearch_subgraphs_by_keywordto find candidate subgraphs.
- Useget_deployment_30day_query_countsto verify activity and aid selection.
- Useget_top_subgraph_deploymentsif a contract address is provided.
- Fetch and understand the subgraph schema using the appropriateget_schema_by_tool.
- Convert your question into an appropriate GraphQL query.
- Execute the query using the correctexecute_query_by_tool based on the identifier type and confirmed active deployment.
- Present the results in a readable format.

The server provides predefined prompts for most tools (as discoverable via MCP'slist_prompts):

- get_schema_by_deployment_id: Get the schema for a deployment ID.
- get_schema_by_subgraph_id: Get the schema for a subgraph ID.
- get_schema_by_ipfs_hash: Get the schema for an IPFS hash.
- execute_query_by_deployment_id: Run a GraphQL query against a deployment ID.
- execute_query_by_subgraph_id: Run a GraphQL query against a subgraph ID.
- execute_query_by_ipfs_hash: Run a GraphQL query against an IPFS hash.
- get_top_subgraph_deployments: Get top subgraphs for a contract on a specific chain.

- graphql://subgraph: Provides the detailedSubgraph Server Instructionsused by the LLM, including the workflow for different user goals (address lookup, finding subgraphs for a contract, querying by ID, getting schema) and important usage notes.

Below is a reference for theSubgraph Server Instructions:

Interacting with The Graph Subgraphs IMPORTANT: ALWAYS verify query volumes using get_deployment_30day_query_counts for any potential subgraph candidate before selecting or querying it. This step is NON-OPTIONAL. Failure to do so may result in using outdated or irrelevant data. Follow this sequence strictly: 1. Analyze User Request:  Identify the protocol name (e.g., "Uniswap", "Aave", "ENS").  Note any specific version or blockchain network mentioned by the user.  Determine the goal: Query data? Get schema? 2. Initial Search & Preliminary Analysis:  Use search_subgraphs_by_keyword with the most generic term for the protocol (e.g., if "Uniswap v3 on Ethereum", initially search only for "Uniswap").  Examine displayName and other metadata in the search results for version and network information. 3. Mandatory Query Volume Check & Clarification (If Needed):  ALWAYS extract the IPFS hashes (ipfsHash) for all potentially relevant subgraphs identified in Step 2.  ALWAYS use get_deployment_30day_query_counts for these IPFS hashes.  If Ambiguous (Multiple Versions/Chains with significant volume):  Present a summary to the user, including the 30-day query counts for each option. For example: "I found several Uniswap subgraphs. Uniswap v3 on Ethereum is the most active (X queries last 30 days). I also see Uniswap v2 on Ethereum (Y queries) and Uniswap v3 on Arbitrum (Z queries). Which specific version and network are you interested in?"  If Still Unclear (Information Missing and Not Inferable even with query volumes):  If version/chain information is genuinely missing from search results and user input, and query volumes don't offer a clear path (e.g. all relevant subgraphs have very low or no volume), ask for clarification directly. Example: "I found several subgraphs for 'ExampleProtocol', but none have significant query activity. Could you please specify the version and blockchain network you're interested in?"  Do NOT proceed to Step 4 without completing this query volume verification. 4. Select Final Subgraph (Post Query Volume Check & Clarification):  After the keyword search, mandatory query volume check, and any necessary clarification, you should have a clear target protocol, version, and network.  Identify all candidate subgraphs from your Step 2 search_subgraphs_by_keyword results that match these clarified criteria.  If there is more than one such matching subgraph:  You should have already fetched their query counts in Step 3.  Select the subgraph with the highest total_query_count among them.  If only one subgraph precisely matches the criteria, that is your selected subgraph.  When presenting your chosen subgraph or asking for final confirmation before querying, ALWAYS state its 30-day query volume to demonstrate this check has been performed. For example: "I've selected the 'Uniswap v3 Ethereum' subgraph, which has X queries in the last 30 days. Shall I proceed to get its schema?"  If the selected subgraph's query count is very low (and this wasn't already discussed during clarification), briefly inform the user. 5. Execute Action Using the Identified Subgraph:  Identify the ID Type: (Subgraph ID, Deployment ID, or IPFS Hash - note that search_subgraphs_by_keyword returns id for Subgraph ID and ipfsHash for current deployment's IPFS hash).  Determine the Correct Tool based on Goal & ID Type:  Goal: Query Data  Subgraph ID (id from search) → execute_query_by_subgraph_id  Deployment ID (0x...) → execute_query_by_deployment_id  IPFS Hash (ipfsHash from search) → execute_query_by_ipfs_hash  Goal: Get Schema  Subgraph ID → get_schema_by_subgraph_id  Deployment ID → get_schema_by_deployment_id  IPFS Hash → get_schema_by_ipfs_hash  Write Clean GraphQL Queries: Simple structure, omit 'variables' if unused, include only essential fields. Special Case: Contract Address Lookup  ONLY when a user explicitly provides a contract address (0x...) AND asks for subgraphs related to it:  Identify the blockchain network for the address (ask user if unclear).  Use get_top_subgraph_deployments with the provided contract address and chain name.  Process and use the resulting IPFS hashes as needed. Crucially, before using any of these IPFS hashes for querying, first use get_deployment_30day_query_counts with their IPFS hashes to verify recent activity. ID Type Reference:  Subgraph ID: Typically starts with digits and letters (e.g., 5zvR82...)  Contract Address: A shorter hexadecimal string, typically 42 characters long including the "0x" prefix (e.g., 0x1a3c9b1d2f0529d97f2afc5136cc23e58f1fd35b).  Deployment ID: A longer hexadecimal string, typically 66 characters long including the "0x" prefix (e.g., 0xc5b4d246cf890b0b468e005224622d4c85a8b723cc0b8fa7db6d1a93ddd2e5de). Use length to distinguish from a Contract Address.  IPFS Hash: Typically starts with Qm... For the purpose of get_deployment_30day_query_counts, use the \'IPFS Hash\' (Qm...).  Note search_subgraphs_by_keyword and get_top_subgraph_deployments returns ipfsHash. Best Practices:  When using GraphQL, if unsure about the structure, first get the schema to understand available entities and fields.  Create focused queries that only request necessary fields.  For paginated data, use appropriate limit parameters.  Use variables for dynamic values in queries.

The server exposes Prometheus metrics for monitoring its performance and behavior.

When running in SSE mode, a metrics server is started on a separate port.

You can configure the port and host for the metrics server using theMETRICS_PORTandMETRICS_HOSTenvironment variables.

The following application-specific metrics are exposed:

- mcp_tool_calls_total{tool_name, status}: A counter for the number of MCP tool calls.

- tool_name: The name of the MCP tool being called (e.g.,get_schema_by_deployment_id).
- status: The result of the call (successorerror).

- endpoint_type: The type of query or endpoint being hit (e.g.,get_schema_by_deployment_id,subgraphs/id).
- status: The result of the request (successorerror).

Additionally, theaxum-prometheuslibrary provides standard HTTP request metrics for the metrics server itself (prefixed withhttp_).

If you encounter "Request timed out" or "MCP error -32001" errors, this typically indicates that GraphQL queries are taking longer than the configured timeout to complete.

If you're running your own local server instance:
- Increase the timeoutusing theSUBGRAPH_REQUEST_TIMEOUT_SECONDSenvironment variable:

export SUBGRAPH_REQUEST_TIMEOUT_SECONDS=300 # 5 minutes

If you're using the remote hosted service:
- Contact support- Timeout settings are managed by the hosted service and cannot be customized by end users.
-

Check query complexity- Very complex queries with large result sets may need longer timeouts or query optimization.

Verify The Graph Gateway status- Occasional timeout issues may be due to temporary Gateway performance issues.

Default Timeout: Local server instances use a 120-second timeout by default (increased from 30 seconds in earlier versions). Remote hosted service timeout settings may differ.

- "API key not found": Ensure yourGATEWAY_API_KEYenvironment variable is set correctly
- "Configuration error": Check that your Gateway API key is valid and has appropriate permissions
- Connection refused: Verify the server is running and accessible on the configured port

Contributions are welcome! Please feel free to submit a Pull Request.

Provides real-time financial market data using the Alpha Vantage API.

A stock market data service for querying A-share market data from Sina and Tencent Finance.

Perform financial analysis using the DART API and Claude.

Funding rounds, acquisitions & exec moves — deduped, enriched, typed. Query over REST, stream over webhooks, or hand to your agent over MCP. 50 free credits.

Access financial datasets from the Federal Reserve Economic Data (FRED) API.

Provides real-time financial data using the Tushare API.

Provides real-time financial data from Yahoo Finance.

Access US Treasury data via the Fiscal Data API to fetch statements, historical data, and generate reports.

Real-time forex macroeconomic API for all major currency pairs sourced from central bank announcements.

Retrieve and process economic data from the International Monetary Fund (IMF) API, including datasets, time series, indicators, and countries.