# TheGraph MCP Server

An MCP server that powers AI agents with indexed blockchain data from [The Graph](https://thegraph.com/).

<a href="https://glama.ai/mcp/servers/@Data-Nexus-Web3/thegraph-mcp">
  <img width="380" height="200" src="https://glama.ai/mcp/servers/@Data-Nexus-Web3/thegraph-mcp/badge" alt="TheGraph Server MCP server" />
</a>

![GitHub License](https://img.shields.io/github/license/Data-Nexus-Web3/thegraph-mcp) 
![GitHub Last Commit](https://img.shields.io/github/last-commit/Data-Nexus-Web3/thegraph-mcp) 
![Python Version](https://img.shields.io/badge/python-3.10%2B-blue)

## Available Tools

### 1. searchSubgraphs
Searches for subgraphs on The Graph Network by name or description. Uses the Network Subgraph's full-text search to find matching subgraphs, returning a list sorted by signal amount (highest first). Results include the subgraph's GraphQL schema, so agents can go directly from discovery to querying without a separate schema fetch.

**Parameters:**
- `searchQuery`: The search term to find matching subgraphs (e.g., "uniswap", "aave", "ENS")

### 2. getSubgraphSchema
Fetches the schema of a specified subgraph, providing AI agents with the context needed to generate GraphQL queries.

**Parameters:**
- `subgraphId`: The subgraph ID (e.g., "QmZBQcF...")
- `asText`: Output format flag
  - `true`: Returns human-readable GraphQL schema
  - `false`: Returns JSON schema (default)

### 3. querySubgraph
Executes GraphQL queries against a specified subgraph. While queries are typically generated by AI, you can also manually craft your own.

**Parameters:**
- `subgraphId`: The subgraph ID
- `query`: GraphQL query string


## Installation

1. **Install uv** (if not already installed)
    ```bash
    curl -LsSf https://astral.sh/uv/install.sh | sh
    ```
2. **Clone the Repository**
    ```bash
    git clone https://github.com/Data-Nexus-Web3/thegraph-mcp.git
    ```
3. **Get an API Key**

    Sign up at [The Graph Studio](https://thegraph.com/studio/) to get an API key (free for the first 100k queries)

4. **Add the MCP Server**

    **Claude Code:**
    ```bash
    claude mcp add -e THEGRAPH_API_KEY=your_api_key_here thegraph-mcp -- uv --directory path/to/thegraph-mcp run main.py
    ```

    **Claude Desktop / Other MCP Clients:**

    Add the following to your client's MCP config file (e.g. `claude_desktop_config.json`):
    ```json
    {
      "mcpServers": {
        "thegraph-mcp": {
          "command": "uv",
          "args": ["--directory", "path/to/thegraph-mcp", "run", "main.py"],
          "env": {
            "THEGRAPH_API_KEY": "your_api_key_here"
          }
        }
      }
    }
    ```

## Example Prompts

Here are some natural language prompts to trigger the tools:

### Subgraph Discovery
- "Find me a subgraph for Uniswap on Ethereum"
- "Search for Aave subgraphs"
- "What subgraphs are available for ENS?"

### Schema Queries
- "Show me the schema for the Uniswap V3 Ethereum subgraph in a readable format"
- "What entities and fields are available in the Aave V3 subgraph?"
- "I need to understand the data model of subgraph QmZBQcF..., can you fetch its schema?"

### Data Queries
- "Find the top 5 tokens by trading volume in the last 24 hours on Uniswap V3 Ethereum"
- "Show me all pairs with liquidity greater than 1 million USD on Uniswap"
- "Get the latest 10 swap events from subgraph QmZBQcF..., including token symbols and amounts"

### Analysis Tasks
- "What is the highest APR market on Aave mainnet?"
- "Compare the liquidity of ETH and USDC pairs on Uniswap Ethereum"
- "Find the most active lending markets on Aave by deposit volume"

### Combined Tasks
- "Find a Uniswap subgraph on Ethereum, check its schema, then help me write a query to find high-value swaps"
- "What data can I get from Aave on Ethereum? Show me the schema and then query the top markets by TVL"
- "Using subgraph QmZBQcF..., analyze the market impact of large trades by first understanding the schema and then querying relevant events"

## License
This project is licensed under the MIT License. See the [LICENSE](LICENSE) file for details.