Celo MCP Server

Celo MCP 服务

一个用于与 Celo 区块链交互的 Model Context Protocol（MCP）服务。此服务提供对 Celo 区块链数据、代币操作、NFT 管理、智能合约交互、交易处理和治理操作的全面访问。

安装

1. 克隆仓库：

git clone https://github.com/celo-org/celo-mcp
cd celo-mcp

2. 安装依赖项：

pip install -e .

3. 设置环境变量（可选）：

export CELO_MCP_RPC_URL="https://forno.celo.org"  # Default: Celo mainnet
export CELO_MCP_USE_TESTNET=true                  # Use Celo Sepolia instead

MCP 集成

Cursor IDE 集成

要将此 MCP 服务与 Cursor IDE 配合使用，请将以下配置添加到 MCP 设置文件（~/.cursor/mcp.json）中：

{
  "mcpServers": {
    "celo-mcp": {
      "command": "uvx",
      "args": ["--refresh", "celo-mcp"]
    }
  }
}

--refresh 标志可确保 MCP 服务启动时始终加载最新代码。

Claude Desktop 集成

对于 Claude Desktop，请将以下配置添加到 MCP 设置文件（macOS 上为 ~/Library/Application Support/Claude/claude_desktop_config.json）中：

{
  "mcpServers": {
    "celo-mcp": {
      "command": "uvx",
      "args": ["--refresh", "celo-mcp"]
    }
  }
}

远程连接（Streamable HTTP）

此服务也可以作为基于 Streamable HTTP 的远程 MCP 端点运行，客户端只需通过一个 URL 连接，无需在本地安装 Python。上面的 stdio 设置保持不变；这是额外提供的一种传输方式。

以 HTTP 模式运行：

celo-mcp-server --transport http --port 3000
# or via env:
MCP_TRANSPORT=http PORT=3000 celo-mcp-server

然后将任何支持远程连接的 MCP 客户端指向该 URL：

{
  "mcpServers": {
    "celo": { "url": "https://<your-host>/mcp" }
  }
}

配置（环境变量）：

变量	用途	默认值
MCP_TRANSPORT	stdio 或 http	stdio
HOST / PORT	HTTP 绑定主机 / 端口	127.0.0.1 / 3000
MCP_ALLOWED_HOSTS	SDK DNS 重绑定检查接受的主机名，以逗号分隔。设为你的公共主机名，或设为 * 以禁用检查	仅 localhost
MCP_CORS_ORIGINS	允许的来源，以逗号分隔（或设为 *）	*
MCP_RATE_LIMIT / MCP_RATE_WINDOW	每个客户端在每个时间窗口（秒）内的请求数；/health 不受限制	60 / 60
MCP_TRUST_PROXY	基础设施追加的 X-Forwarded-For 跳数，以便速率限制器按客户端而非代理地址进行计数。单个反向代理时设为 1，位于 Google 外部负载均衡器之后时设为 2。从右侧开始计数，参见部署	未设置
MCP_AUTH_TOKEN	如果设置，则访问 /mcp 时需要提供 Authorization: Bearer <token>	未设置（开放访问）
CELO_MCP_RPC_URL	Celo RPC 端点	所选网络的 Forno
CELO_MCP_USE_TESTNET	使用 Celo Sepolia（链 ID 11142220）而非主网	false
CELO_MCP_FAUCET_API_KEY	启用水龙头工具。在 faucet.celo.org/keys 创建密钥，参见水龙头访问	未设置（水龙头工具已禁用）

GET /health 会在托管健康检查时返回 200。容器和托管说明请参见 docs/DEPLOYMENT.md。

用法

运行服务

# Run the MCP server
python -m celo_mcp.server

# Or use the CLI entry point
celo-mcp-server

可用工具

区块链数据操作

1. get_network_status

   • 获取当前网络状态和连接信息
   • 无需参数

2. get_block

   • 按区块编号、哈希或 "latest" 获取区块信息
   • 参数：block_identifier、include_transactions（可选）

3. get_transaction

   • 按哈希获取交易详情
   • 参数：tx_hash

4. get_account

   • 获取账户信息，包括余额和 nonce
   • 参数：address

5. get_latest_blocks

   • 获取近期区块的信息
   • 参数：count（可选，默认值：10，最大值：100）

代币操作

6. get_token_info

   • 获取详细的代币信息（名称、符号、小数位数、供应量）
   • 参数：token_address

7. get_token_balance

   • 获取特定地址的代币余额
   • 参数：token_address、address

8. get_celo_balances

   • 获取某地址的 CELO 和稳定币余额
   • 参数：address

NFT 操作

9. get_nft_info

   • 获取 NFT 信息，包括元数据和集合详情
   • 参数：contract_address、token_id

10. get_nft_balance

    • 获取某个地址的 NFT 余额（支持 ERC721 和 ERC1155）
    • 参数：contract_address、address、token_id（ERC1155 可选）

智能合约操作

11. call_contract_function

    • 调用合约的只读函数
    • 参数：contract_address、function_name、abi、function_args（可选）、from_address（可选）

12. estimate_contract_gas

    • 估算调用合约函数所需的 Gas
    • 参数：contract_address、function_name、abi、from_address、function_args（可选）、value（可选）

交易操作

13. estimate_transaction

    • 估算交易所需的 Gas 和费用
    • 参数：to、from_address、value（可选）、data（可选）

14. get_gas_fee_data

    • 获取当前 Gas 费用数据，包括 EIP-1559 费用
    • 无需参数

治理操作

15. get_governance_proposals

    • 获取 Celo 治理提案，支持分页
    • 参数：include_inactive（可选）、include_metadata（可选）、page（可选）、page_size（可选）、offset（可选）、limit（可选）

16. get_proposal_details

    • 获取特定治理提案的详细信息，包括内容和投票历史
    • 参数：proposal_id

质押操作

17. get_staking_balances

    • 获取某个地址的质押余额，包括按验证者组细分的活跃质押和待处理质押
    • 参数：address

18. get_activatable_stakes

    • 获取可激活并赚取奖励的待处理质押信息
    • 参数：address

19. get_validator_groups

    • 获取所有验证者组的信息，包括其成员、投票数、容量和性能指标
    • 无需参数

20. get_validator_group_details

    • 获取特定验证者组的详细信息，包括其成员和性能数据
    • 参数：group_address

21. get_total_staking_info

    • 获取全网质押信息，包括总投票数和参与度指标
    • 无需参数

水龙头操作

两个水龙头工具仅限测试网使用，且需要 CELO_MCP_FAUCET_API_KEY（见下文 水龙头访问）。

22. request_faucet_funds

    • 为某个地址申请测试网 CELO。如果请求仍处于开放状态时款项到账，则返回付款交易哈希；否则返回用于轮询的 request_key
    • 每次请求发送 3 CELO，且仅发送 CELO ——不发送 USDm 或其他稳定币
    • 参数：beneficiary、可选的 network（celo-sepolia）、可选的 wait（默认为 true）

23. get_faucet_request_status

    • 检查已排队的水龙头请求是否已付款
    • 参数：request_key、可选的 network（celo-sepolia）

水龙头访问

水龙头的浏览器流程启用了 reCAPTCHA v3，得分会对无头调用者十分不利，因此水龙头工具改用其 API 密钥路径。请在 faucet.celo.org/keys 创建密钥（使用 GitHub 登录；最多可创建 2 个密钥，有效期为 90 天），并将其设置在 MCP 客户端的 env 块中：

{
  "mcpServers": {
    "celo-mcp": {
      "command": "uvx",
      "args": ["celo-mcp"],
      "env": { "CELO_MCP_FAUCET_API_KEY": "cfk_..." }
    }
  }
}

密钥从环境中读取，绝不会作为工具参数传递，因此不会进入模型的上下文或对话记录。

限额由水龙头设定，而非此服务设定：每 24 小时 10 次请求，按 GitHub 账号和受益地址分别计数——持有两个密钥不会使限额翻倍。此外，所有密钥还共同受每日总量和 10 分钟突发请求上限的限制。唯一支持的网络是 celo-sepolia（链 ID 11142220）；没有主网水龙头。

水龙头在 openapi.json 和 llms-full.txt 中公布其 API 合约；如果金额或限额发生变化，请以这些文档为准。

**部署说明：**除非设置了 MCP_AUTH_TOKEN，否则 HTTP 传输处于开放状态。仅在 stdio 或经过身份验证的部署中配置水龙头密钥——否则，任何能访问 /mcp 的人都可以将你的每日限额用于任意地址，而且密钥可能因滥用而被撤销。

主要功能

代币支持

• ERC20 标准：全面支持 ERC20 代币
• Mento 稳定代币：内置支持 USDm、EURm 和 BRLm（以前称为 cUSD、cEUR 和 cREAL），以及 XOFm、KESm、PHPm、COPm 和 GHSm
• 余额查询：获取代币余额，并正确格式化小数位
• 代币信息：获取名称、符号、小数位数和总供应量

NFT 支持

• 多标准：同时支持 ERC721 和 ERC1155 标准
• 自动检测：使用 ERC165 自动检测 NFT 标准
• 元数据获取：从 URI 获取并解析 NFT 元数据
• IPFS 支持：内置 IPFS 网关支持，用于获取元数据
• 藏品信息：获取藏品级别的信息

智能合约交互

• 函数调用：调用只读合约函数
• Gas 估算：估算合约交互的 Gas 费用
• ABI 管理：解析和管理合约 ABI
• 事件处理：获取并解码合约事件
• 交易构建：构建合约交易

交易管理

• Gas 估算：准确估算交易的 Gas
• EIP-1559 支持：采用包含基础费用和优先费用的现代费用结构
• 交易模拟：在执行前模拟交易
• 费用计算：根据网络状况动态计算费用

治理支持

• 提案管理：获取并分析 Celo 治理提案
• 投票数据：访问提案投票历史和结果
• 元数据集成：从 GitHub 仓库获取提案元数据
• 分页支持：高效浏览大量提案

质押支持

• 质押余额：按验证者组查看活跃和待处理的质押
• 激活跟踪：检查哪些待处理质押可以激活
• 验证者信息：全面的验证者和验证者组数据
• 性能指标：验证者评分、选举状态和容量
• 网络统计：总投票权和质押参与情况

开发

运行测试

# Install development dependencies
pip install -e ".[dev]"

# Run tests
pytest

# Run with coverage
pytest --cov=celo_mcp

代码质量

# Format code
black src/
isort src/

# Lint code
flake8 src/
mypy src/

贡献

1. Fork 此仓库
2. 创建功能分支
3. 进行更改
4. 为新功能添加测试
5. 确保所有测试通过
6. 提交拉取请求

许可证

本项目采用 MIT 许可证授权，详情请参阅 LICENSE 文件。

支持

如有问题、疑问或希望贡献，请：

1. 查看 GitHub 上现有的问题
2. 创建新问题并提供详细信息
3. 参与社区讨论

致谢

• 基于 Model Context Protocol (MCP) 框架构建
• 使用 Web3.py 与 Ethereum/Celo 区块链交互
• 支持 Celo 生态系统及其稳定代币基础设施