The Graph MCP Server for AI Agents

Overview

The Graph MCP Server is a lightweight Model Context Protocol (MCP) server that exposes indexed blockchain data from The Graph to AI agents and LLM-based applications. Instead of querying raw nodes or running expensive on-chain scans, agents can request pre-indexed, queryable context via a small HTTP API. This reduces latency, improves reliability, and provides structured on-chain facts that are suitable as context for model prompts and reasoning.

This server sits between The Graph (subgraphs / GraphQL endpoints) and your agent runtime. It can aggregate subgraph queries, cache responses, and present a consistent tool-like interface (MCP-style) that agents can call to retrieve domain-specific blockchain insights—prices, balances, transfers, NFT metadata, and more—without embedding raw GraphQL logic into the agent itself.

Features

• Exposes MCP-compatible HTTP endpoints for agent consumption
• Proxies and aggregates GraphQL queries to The Graph subgraphs
• Configurable caching to reduce query latency and rate limits
• Simple configuration for registering multiple subgraphs / networks
• Lightweight deployment: Node + Docker friendly
• Health and metrics endpoints for observability
• Example request/response formats suitable for prompt injection into LLMs

Installation / Configuration

Quick start (Node.js):

# Clone the repo
git clone https://github.com/kukapay/thegraph-mcp.git
cd thegraph-mcp

# Install dependencies and start (assuming a Node.js project)
npm install
npm run build
npm start

Docker build and run:

# Build the Docker image
docker build -t thegraph-mcp .

# Run with environment variables (see table below)
docker run -p 8080:8080 \
  -e MCP_PORT=8080 \
  -e THEGRAPH_DEFAULT_URL=https://api.thegraph.com/subgraphs/name/example/subgraph \
  -e CACHE_TTL=30 \
  thegraph-mcp

Environment configuration (common variables):

Example minimal config (config.json):

{
  "port": 8080,
  "cacheTTL": 30,
  "subgraphs": [
    {
      "name": "uniswap-v2",
      "chainId": 1,
      "url": "https://api.thegraph.com/subgraphs/name/uniswap/uniswap-v2"
    }
  ]
}

Available Tools / Resources

The MCP server exposes a small set of HTTP endpoints that agents can use:

• GET /health — basic health check
• GET /tools — list of available tools (registered subgraphs and query capabilities)
• POST /query — run a predefined or free-form GraphQL query against a named subgraph
• GET /metrics — optional Prometheus-style metrics (if enabled)

Example /tools response (JSON):

{
  "tools": [
    {
      "id": "uniswap-v2-ticks",
      "name": "Uniswap V2",
      "description": "Query pool reserves, prices, and swaps",
      "params": ["poolAddress", "sinceBlock"]
    }
  ]
}

POST /query body (example):

{
  "subgraph": "uniswap-v2",
  "query": "{ pair(id: \"0x...\") { reserve0 reserve1 token0 { symbol } } }"
}

Use Cases

• DeFi research agent: An LLM agent that builds a short report on liquidity and price impact for a given Uniswap pool. The agent calls /tools to discover the Uniswap tool, then issues a /query for reserves and recent swaps to compute slippage and suggest trade size.
• Portfolio analytics: Periodically fetch token balances across multiple wallets by querying token transfer and balance subgraphs. Cache responses for N seconds to avoid overloading indexing nodes while keeping information fresh for user-facing dashboards.
• On-chain due diligence: Retrieve token holder distribution, recent large transfers, and contract metadata for token audits. Agents can assemble findings into a concise summary and highlight anomalous movements.
• NFT provenance and metadata: For marketplaces and collectors, fetch ownership history and metadata snapshots (IPFS gateways) via NFT subgraphs and provide context for valuation models.

Example: Fetching context from an agent (JavaScript)

const fetch = require('node-fetch');

async function fetchPoolContext(poolAddress) {
  const resp = await fetch('http://localhost:8080/query', {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({
      subgraph: 'uniswap-v2',
      query: `{ pair(id: "${poolAddress.toLowerCase()}") { reserve0 reserve1 token0 { symbol } } }`
    })
  });
  return await resp.json();
}

This server is intended for developers building LLM/agent integrations that need reliable, indexed on-chain context without handling raw node queries. Configure subgraphs relevant to your domain, keep cache settings tuned for your query volume, and expose a small set of tools your agents can call reproducibly. For full source, examples, and contribution guidelines, see the repository: https://github.com/kukapay/thegraph-mcp.