Docs
Search⌘ K
  • Home
  • About The Graph
  • Supported Networks
  • Protocol Contracts
  • Subgraphs
    • Substreams
      • Token API
        • AI Suite
          • Indexing
            • Resources
              AI Suite > Subgraph MCP

              3 minutes

              Claude Desktop

              This guide walks you through the integration of Subgraph Model Context Protocol⁠ (MCP) to access Subgraph data via natural language conversations with Claude.

              Prerequisites

              • Node.js⁠ installed and available in your path
              • Claude Desktop⁠ installed (latest version)
              • A Gateway API key from Subgraph Studio

              Installation Options

              Option 1: Using npx (Recommended)

              Configuration Steps using npx

              1. Open Configuration File

              Navigate to your claude_desktop_config.json file:

              Settings > Developer > Edit Config

              • OSX: ~/Library/Application Support/Claude/claude_desktop_config.json
              • Windows: %APPDATA%\Claude\claude_desktop_config.json
              • Linux: .config/Claude/claude_desktop_config.json

              2. Add Configuration

              Paste the following settings into your config file:

              1{2  "mcpServers": {3    "subgraph": {4      "command": "npx",5      "args": ["mcp-remote", "--header", "Authorization:${AUTH_HEADER}", "https://subgraphs.mcp.thegraph.com/sse"],6      "env": {7        "AUTH_HEADER": "Bearer GATEWAY_API_KEY"8      }9    }10  }11}

              3. Add Your Gateway API Key

              Replace GATEWAY_API_KEY with your API key from Subgraph Studio.

              4. Save and Restart

              Once you’ve entered your Gateway API key into your settings, save the file and restart Claude Desktop.

              Option 2: Building from Source

              Requirements

              • Rust (latest stable version recommended: 1.75+)
                1curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
                Follow the on-screen instructions. For other platforms, see the official Rust installation guide⁠.

              Installation Steps

              1. Clone and Build the Repository

                1git clone [email protected]:graphops/subgraph-mcp.git2cd subgraph-mcp3cargo build --release
              2. Find the Command Path

                After building, the executable will be located at target/release/subgraph-mcp inside your project directory.

                • Navigate to your subgraph-mcp directory in terminal
                • Run pwd to get the full path
                • Combine the output with /target/release/subgraph-mcp
              3. Configure Claude Desktop

                Open your claude_desktop_config.json file as described above and add:

                1{2  "mcpServers": {3    "subgraph": {4      "command": "/path/to/your/subgraph-mcp/target/release/subgraph-mcp",5      "env": {6        "GATEWAY_API_KEY": "your-api-key-here"7      }8    }9  }10}

                Replace /path/to/your/subgraph-mcp/target/release/subgraph-mcp with the actual path to the compiled binary.

              Using The Graph Resource in Claude

              After configuring Claude Desktop:

              1. Restart Claude Desktop
              2. Start a new conversation
              3. Click on the context menu (top right)
              4. Add “Subgraph Server Instructions” as a resource by adding graphql://subgraph to your chat context

              Important: Claude Desktop may not automatically utilize the Subgraph MCP. You must manually add “Subgraph Server Instructions” resource to your chat context for each conversation where you want to use it.

              Troubleshooting

              To enable logs for the MCP when using the npx option, add the --verbose true option to your args array.

              Available Subgraph Tools and Usage

              The Subgraph MCP provides several tools for interacting with Subgraphs:

              Schema Retrieval Tools

              • Get schema by deployment ID: Access the GraphQL schema using a deployment ID (0x…)
              • Get schema by Subgraph ID: Access the schema for the current deployment of a Subgraph (5zvR82…)
              • Get schema by IPFS hash: Access the schema using a Subgraph’s IPFS manifest hash (Qm…)

              Query Execution Tools

              • Execute query by deployment ID/IPFS hash: Run GraphQL queries against specific, immutable deployments
              • Execute query by Subgraph ID: Run GraphQL queries against the latest version of a Subgraph

              Discovery Tools

              • Search subgraphs by keyword: Find subgraphs by keyword in their display names, ordered by signal
              • Get deployment 30-day query counts: Get aggregate query count over the last 30 days for multiple subgraph deployments
              • Get top Subgraph deployments for a contract: Find the top 3 Subgraph deployments indexing a specific contract on a particular chain, ordered by query fees

              Key Identifier Types

              • Subgraph ID (e.g., 5zvR82...): Logical identifier for a subgraph. Use execute_query_by_subgraph_id or get_schema_by_subgraph_id.
              • Deployment ID (e.g., 0x4d7c...): Identifier for a specific, immutable deployment. Use execute_query_by_deployment_id or get_schema_by_deployment_id.
              • IPFS Hash (e.g., QmTZ8e...): Identifier for the manifest of a specific, immutable deployment. Use execute_query_by_deployment_id (the gateway treats it like a deployment ID for querying) or get_schema_by_ipfs_hash.

              Benefits of Natural Language Queries

              One of the most powerful features of the Subgraph MCP integration is the ability to ask questions in natural language. Claude will:

              1. Understand your goal (lookup, find Subgraphs, query, get schema)
              2. Find relevant deployments if needed
              3. Fetch and interpret the Subgraph schema
              4. Convert your question into an appropriate GraphQL query
              5. Execute the query and present the results in a readable format

              Example Natural Language Queries

              1What are the pairs with maximum volume on deployment 0xde0a7b5368f846f7d863d9f64949b688ad9818243151d488b4c6b206145b9ea3?
              1Which tokens have the highest market cap in this Subgraph?
              1Show me the most recent 5 swaps for the USDC/ETH pair
              1Find the top subgraphs for contract 0x1f98431c8ad98523631ae4a59f267346ea31f984 on arbitrum-one
              ⁠Edit on GitHub⁠

              IntroductionCline
              On this page
              • Prerequisites
              • Installation Options
              • Option 1: Using npx (Recommended)
              • Option 2: Building from Source
              • Using The Graph Resource in Claude
              • Troubleshooting
              • Available Subgraph Tools and Usage
              • Schema Retrieval Tools
              • Query Execution Tools
              • Discovery Tools
              • Key Identifier Types
              • Benefits of Natural Language Queries
              • Example Natural Language Queries
              The GraphStatusTestnetBrand AssetsForumSecurityPrivacy PolicyTerms of Service