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 エンドポイントとしても実行できるため、クライアントはローカルに Python をインストールせず、単一の URL で接続できます。上記の 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

    • コントラクト関数の呼び出しに必要なガスを見積もります
    • パラメーター：contract_address、function_name、abi、from_address、function_args（省略可能）、value（省略可能）

トランザクション操作

13. estimate_transaction

    • トランザクションに必要なガスとコストを見積もります
    • パラメーター：to、from_address、value（省略可能）、data（省略可能）

14. get_gas_fee_data

    • 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

    • 総投票数や参加指標など、ネットワーク全体のステーキング情報を取得します
    • パラメーターは不要です

Faucet 操作

どちらの faucet ツールもテストネット専用で、CELO_MCP_FAUCET_API_KEY が必要です（下記の Faucet へのアクセスを参照）。

22. request_faucet_funds

    • アドレス宛てにテストネット CELO をリクエストします。リクエストが開いている間に送金が実行された場合は、送金トランザクションのハッシュを返します。それ以外の場合は、ポーリングに使用する request_key を返します
    • リクエストごとに 3 CELO を送金します。対象は CELO のみであり、USDm やその他のステーブルコインは含まれません
    • パラメーター：beneficiary、省略可能な network（celo-sepolia）、省略可能な wait（デフォルトは true）

23. get_faucet_request_status

    • キューに入った faucet リクエストが送金済みかどうかを確認します
    • パラメーター：request_key、省略可能な network（celo-sepolia）

Faucetへのアクセス

FaucetのブラウザーフローではreCAPTCHA v3による検証が行われますが、ヘッドレスの呼び出し元は低いスコアを付けられるため、Faucetツールでは代わりに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_..." }
    }
  }
}

キーは環境変数から読み込まれ、ツールの引数として渡されることはないため、モデルのコンテキストや会話の記録には含まれません。

上限はこのサーバーではなくFaucetによって設定されています。24時間あたり10リクエストで、GitHubアカウントと受取人アドレスごとにカウントされます。キーを2つ持っていても利用枠は増えません。さらに、すべてのキーに適用される、1日の全体上限と10分間のバースト上限があります。対応ネットワークはcelo-sepolia（チェーンID 11142220）のみで、メインネット用Faucetはありません。

FaucetはAPI仕様をopenapi.jsonとllms-full.txtで公開しています。金額や上限が変更された場合は、これらを信頼できる情報源として扱ってください。

デプロイに関する注意： MCP_AUTH_TOKENが設定されていない場合、HTTPトランスポートは認証なしで利用できます。Faucetキーはstdioまたは認証済みのデプロイでのみ設定してください。そうしないと、/mcpにアクセスできる人なら誰でも任意のアドレスへの送金に1日の利用枠を使えてしまい、悪用によりキーが取り消されるおそれがあります。

主な機能

トークンのサポート

• ERC20標準：ERC20トークンを完全にサポートします
• Mentoステーブルトークン：USDm、EURm、BRLm（旧称cUSD、cEUR、cREAL）、XOFm、KESm、PHPm、COPm、GHSmを組み込みでサポートします
• 残高の照会：適切な小数点形式でトークン残高を取得します
• トークン情報：名前、シンボル、小数点以下の桁数、総供給量を取得します

NFTのサポート

• 複数規格：ERC721とERC1155の両規格をサポートします
• 自動検出：ERC165を使用してNFT規格を自動検出します
• メタデータの取得：URIからNFTメタデータを取得して解析します
• IPFSのサポート：メタデータ用のIPFSゲートウェイを組み込みでサポートします
• コレクション情報：コレクション単位の情報を取得します

スマートコントラクトの操作

• 関数呼び出し：コントラクトの読み取り専用関数を呼び出します
• ガスの見積もり：コントラクト操作にかかるガスコストを見積もります
• ABI管理：コントラクトのABIを解析、管理します
• イベント処理：コントラクトイベントを取得してデコードします
• トランザクションの構築：コントラクトのトランザクションを構築します

トランザクション管理

• ガスの見積もり：トランザクションのガスを正確に見積もります
• 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. リポジトリをフォークします
2. 機能ブランチを作成します
3. 変更を加えます
4. 新しい機能のテストを追加します
5. すべてのテストが成功することを確認します
6. プルリクエストを送信します

ライセンス

このプロジェクトはMIT Licenseの下でライセンスされています。詳細についてはLICENSEファイルを参照してください。

サポート

質問、問題、貢献については、以下をお願いします。

1. GitHubで既存のイシューを確認します
2. 詳細な情報を添えて新しいイシューを作成します
3. コミュニティのディスカッションに参加します

謝辞

• Model Context Protocol（MCP）フレームワークを基盤として構築されています
• Ethereum/Celo ブロックチェーンとの連携には Web3.py を使用しています
• Celo エコシステムとそのステーブルトークンインフラストラクチャをサポートしています