Graph MCP服务器
全面的模型上下文协议（MCP）服务器，提供对The Graph的令牌API和子图的访问，以查询EVM兼容的区块链。该服务器使AI助手能够查询令牌数据、NFT所有权、DEX流动性池以及针对任何子图的自定义GraphQL查询。
特性
- 令牌操作：查询令牌余额、转账和持有人信息
- NFT操作：获取NFT所有权和持有人数据
- DEX运营：从Uniswap和其他协议访问流动性池信息
- 子图查询：对The Graph上的任何子图执行自定义GraphQL查询
- 查询模板：流行子图的预构建查询（Uniswap、Aave、Compound、ENS）
- 多个网络：支持以太坊主网、Arbitrum、Avalanche、Base、BSC、Optimism、Polygon和Unichain
- MCP集成：支持HTTP传输的完整模型上下文协议
安装
npm install配置
创建一个 .env 文件基于 .env.example:
cp .env.example .env设置您的配置：
# Required: Get your token from https://thegraph.com/market/
THEGRAPH_API_TOKEN=your_token_here
# Optional: Get your subgraph API key from https://thegraph.com/studio/apikeys/
# Only needed if querying subgraphs by ID via gateway
THEGRAPH_SUBGRAPH_API_KEY=your_subgraph_key_here
# Optional: Default network for API requests
DEFAULT_NETWORK=mainnet
# Optional: Server configuration
PORT=3000
HOST=localhost用法
发展
npm run dev生产
npm run build
npm start观看模式
npm run watch可用工具
令牌工具
thegraph_token_balances
获取钱包地址的ERC-20和本机代币余额。
参数：
network（必填）：网络ID（主网、仲裁一、雪崩、基础、平衡计分卡、乐观、多边形、单链）address（必填）：钱包地址（0x…）limit（可选）：每页结果（1-1000，默认值：10）page（可选）：页码（默认：1）
thegraph_token_transfers
获取ERC-20和本机代币转移事件。
参数：
network（必填）：网络IDtransaction_id（可选）：按交易哈希过滤contract（可选）：按合同地址筛选from_address（可选）：按发件人地址筛选to_address（可选）：按收件人地址筛选start_time（可选）：开始时间（UNIX时间戳或日期字符串）end_time（可选）：结束时间（UNIX时间戳或日期字符串）start_block（可选）：最小区块数end_block（可选）：最大区块数limit（可选）：每页结果（1-1000，默认值：10）page（可选）：页码（默认：1）
thegraph_token_holders
获取特定合约按余额排名的顶级代币持有者。
参数：
network（必填）：网络IDcontract（必填）：代币合约地址limit（可选）：每页结果（1-1000，默认值：10）page（可选）：页码（默认：1）
NFT工具
thegraph_nft_ownerships
获取钱包地址拥有的NFT代币（ERC-721和ERC-1155）。
参数：
network（必填）：网络IDaddress（必填）：钱包地址contract（可选）：按NFT合约地址筛选token_id（可选）：按令牌ID筛选token_standard（可选）：ERC721或ERC1155include_null_balances（可选）：包括零余额（布尔值）limit（可选）：每页结果（1-1000，默认值：10）page（可选）：页码（默认：1）
thegraph_nft_holders
获取持有NFT收集令牌的钱包地址。
参数：
network（必填）：网络IDcontract（必填）：NFT合同地址token_standard（可选）：ERC721或ERC1155limit（可选）：每页结果（1-1000，默认值：10）page（可选）：页码（默认：1）
DEX工具
thegraph_dex_pools
获取Uniswap流动性池元数据，包括令牌对、费用和协议版本。
参数：
network（必填）：网络IDfactory（可选）：按工厂地址筛选pool（可选）：按池地址筛选input_token（可选）：按输入令牌地址筛选output_token（可选）：按输出令牌地址筛选protocol（可选）：协议名称（uniswap_v1、uniswap_v2、uniswap_v3、uniswai_v4、bancor、curvefi、平衡器）limit（可选）：每页结果（1-1000，默认值：10）page（可选）：页码（默认：1）
子图工具
服务器通过自定义查询和预构建模板提供灵活的子图查询功能。
thegraph_subgraph_query
使用端点URL对任何子图执行自定义GraphQL查询。这是最灵活的选项。
参数：
endpoint（必填）：完整的子图端点URL（例如。，https://api.studio.thegraph.com/query///)query（必填）：GraphQL查询字符串variables（可选）：查询变量对象operationName（可选）：GraphQL操作名称
例子：
{
"endpoint": "https://api.studio.thegraph.com/query/12345/uniswap-v3/v0.0.1",
"query": "query GetPool($poolId: ID!) { pool(id: $poolId) { id token0 { symbol } token1 { symbol } } }",
"variables": { "poolId": "0x8ad599c3a0ff1de082011efddc58f1908eb6e6d8" }
}thegraph_subgraph_query_by_id
使用子图ID执行GraphQL查询。需要 THEGRAPH_SUBGRAPH_API_KEY 待配置。
参数：
subgraphId（必填）：Graph子图ID（部署哈希）query（必填）：GraphQL查询字符串variables（可选）：查询变量对象operationName（可选）：GraphQL操作名称
例子：
{
"subgraphId": "5zvR82QoaXYFyDEKLZ9t6v9adgnptxYpKpSbxtgVENFV",
"query": "query { pairs(first: 5) { id token0 { symbol } token1 { symbol } } }"
}thegraph_subgraph_metadata
获取子图的元数据，包括部署信息、当前块和索引状态。
参数：
endpoint（可选）：子图端点URLsubgraphId（可选）：子图ID（需要API密钥）
注： 必须提供 endpoint 或 subgraphId.
示例响应：
{
"_meta": {
"deployment": "QmXxx...",
"hasIndexingErrors": false,
"block": {
"number": 12345678,
"hash": "0xabc...",
"timestamp": 1234567890
}
}
}thegraph_subgraph_query_template
为流行的子图执行预构建的查询模板。模板包括对Uniswap V2/V3、Aave V3、Compound和ENS的查询。
参数：
templateName（必填）：模板名称（例如，“获取配对信息”、“获取池信息”）endpoint（可选）：子图端点URLsubgraphId（可选）：子图ID（需要API密钥）variables（可选）：覆盖默认模板变量
注： 必须提供 endpoint 或 subgraphId.
可用模板：
- Uniswap V2：“获取配对信息”，“获取顶级配对”
- Uniswap V3：“获取池信息”，“获取最近的掉期交易”
- Aave V3：“获取储备数据”，“获取用户位置”
- 复合物：“获取市场信息”
- ENS：“获取域名信息”，“按所有者获取域名”
- 通用的：“获取子图元数据”
例子：
{
"templateName": "Get Pool Info",
"endpoint": "https://api.studio.thegraph.com/query/12345/uniswap-v3/v0.0.1",
"variables": {
"poolAddress": "0x8ad599c3a0ff1de082011efddc58f1908eb6e6d8"
}
}thegraph_subgraph_list_templates
列出所有可用的查询模板，包括描述和示例变量。
参数： 无
退货： 包含名称、描述、支持的子图和示例变量的模板数组。
GraphQL查询示例
简单查询
query {
pairs(first: 10, orderBy: volumeUSD, orderDirection: desc) {
id
token0 {
symbol
name
}
token1 {
symbol
name
}
reserveUSD
volumeUSD
}
}带变量的查询
query GetUserTokens($userAddress: ID!, $first: Int!) {
user(id: $userAddress) {
id
liquidityPositions(first: $first) {
pair {
token0 { symbol }
token1 { symbol }
}
liquidityTokenBalance
}
}
}变量：
{
"userAddress": "0x1234...",
"first": 20
}时间旅行查询
query GetHistoricalData($blockNumber: Int!) {
pairs(first: 10, block: { number: $blockNumber }) {
id
reserveUSD
volumeUSD
}
}查找子图端点
- 图形资源管理器：浏览子图https://thegraph.com/explorer
- Subgraph工作室：管理您自己的子图https://thegraph.com/studio
- 热门子图:
- Uniswap V2：在图形资源管理器中搜索“Uniswap V2” - Uniswap V3:在图形资源管理器中搜索“Uniswap V3” - Aave V3：在图形资源管理器中搜索“Aave V3” - ENS：在图形资源管理器中搜索“ENS”
支持的网络
mainnet-以太坊主网arbitrum-one-Arbitrum Oneavalanche-雪崩C链base-基地bsc-BNB智能链optimism-乐观主义polygon-多边形（Matic）unichain-Unichain
API终点
服务器公开以下HTTP端点：
GET /health-健康检查和会话状态POST /mcp-初始化会话并发送MCP请求GET /mcp-为MCP通信建立SSE流DELETE /mcp-终止MCP会话
建筑
基于Etherscan MCP服务器模式，具有以下结构：
src/
├── index.ts # Entry point
├── server.ts # MCP server implementation
├── config.ts # Configuration management
├── types/ # TypeScript definitions
│ ├── index.ts # Main types
│ ├── thegraph.ts # The Graph Token API types
│ └── subgraph.ts # Subgraph and GraphQL types
├── tools/ # Tool definitions (11 total)
│ ├── tokens.ts # Token tools (3 tools)
│ ├── nfts.ts # NFT tools (2 tools)
│ ├── dex.ts # DEX tools (1 tool)
│ └── subgraphs.ts # Subgraph tools (5 tools)
├── handlers/ # Tool execution logic
│ ├── tokens.ts # Token handlers
│ ├── nfts.ts # NFT handlers
│ ├── dex.ts # DEX handlers
│ └── subgraphs.ts # Subgraph handlers
└── utils/
├── api.ts # The Graph Token API client
├── subgraphApi.ts # Subgraph GraphQL client
├── queryTemplates.ts # Pre-built query templates
└── schemas.ts # Zod validation schemas错误处理
服务器包括全面的错误处理：
- API身份验证错误（401）
- 无效参数（400）
- 速率限制（429）
- 服务器错误（500）
许可证
麻省理工学院
参考文献
来源
该实施基于：
代币API：
子图：