Africa Energy Data Mcp

Africa Energy Data MCP サーバー

Africa Energy Data API を、Claude、Cursor、その他の MCP 対応クライアント向けのツールとして公開する MCP（Model Context Protocol）サーバーです。

アフリカの全 54 か国を対象に、2000～2022 年の電力、エネルギー、経済データを照会できます。このサーバーには、自動キャッシュ（TTL 10 分）、指数バックオフによる再試行ロジック、入力検証、構造化ログが含まれています。

特長

• 5 つのツール：電力データ、エネルギーデータ、経済指標、ヘルスチェック、国一覧
• 自動キャッシュ：API 呼び出しを減らすための 10 分間のインメモリキャッシュ
• 再試行ロジック：5xx エラーおよびタイムアウト時に、指数バックオフを使って 3 回再試行
• 入力検証：国名、年、年の範囲を検証
• 構造化ログ：詳細なデバッグログを stderr に出力（MCP の stdio に干渉しません）
• 本番環境対応：モジュール設計、エラー処理、タイムアウト管理

セットアップ

1. このリポジトリをクローンまたはダウンロードします

cd africa_energy_mcp

2. 依存関係をインストールします

pip install -r requirements.txt

3. API キーを取得します

1. RapidAPI の Africa Energy Data API にアクセスします
2. RapidAPI に登録するか、ログインします
3. 「Subscribe」をクリックします（無料プランを利用できます）
4. ダッシュボードから API キーをコピーします

4. .env ファイルを作成します

cp .env.example .env

.env を編集し、API キーを貼り付けます：

AFRICA_ENERGY_API_KEY=your_key_here

5. サーバーをローカルでテストします

python server.py

stderr に起動ログが表示されます。停止するには Ctrl+C を押します。

利用可能なツール

1. get_electricity_data

アフリカの国の電力指標を取得します。

パラメーター：

• country（必須）：国名。例：「Kenya」、「Nigeria」
• year（任意）：年で絞り込み（2000～2022）
• metric（任意）：特定の指標名
• unit（任意）：測定単位

例：

{
  "country": "Kenya",
  "year": 2022
}

2. get_energy_data

一般的なエネルギー部門のデータ（アクセス、効率、再生可能エネルギーなど）を取得します。

パラメーター：

• country（必須）：国名
• sub_sector（任意）：「Access」、「Efficiency」、「Renewables」など
• start_year（任意）：年の範囲の開始年（2000～2022）
• end_year（任意）：年の範囲の終了年
• metric（任意）：特定の指標名

例：

{
  "country": "South Africa",
  "start_year": 2010,
  "end_year": 2022
}

3. get_economic_data

GDP、インフレ、人口、エネルギー支出などの経済指標を取得します。

パラメーター：

• country（必須）：国名
• start_year（任意）：年の範囲の開始年
• end_year（任意）：年の範囲の終了年
• metric（任意）：「GDP」、「Inflation」、「Rural population」など
• unit（任意）：測定単位

4. check_api_health

API がオンラインで応答していることを確認します。

パラメーターは不要です。

5. list_countries

サポート対象のアフリカ全 54 か国の一覧を取得します。

パラメーターは不要です。

Claude Desktop に接続する

macOS / Linux

~/.config/claude_desktop_config.json を編集します：

{
  "mcpServers": {
    "africa-energy": {
      "command": "python",
      "args": ["/path/to/africa_energy_mcp/server.py"]
    }
  }
}

/path/to/africa_energy_mcp をリポジトリへの絶対パスに置き換えます。

Windows

%APPDATA%\Claude\claude_desktop_config.json を編集します：

{
  "mcpServers": {
    "africa-energy": {
      "command": "python",
      "args": ["C:\\path\\to\\africa_energy_mcp\\server.py"]
    }
  }
}

その後、Claude Desktop を再起動します。MCP ツールの一覧にツールが表示されます。

Cursor に接続する

1. Cursor の設定を開きます（Cmd/Ctrl + ,）
2. 「MCP」を検索します
3. 「Edit in Settings JSON」をクリックします
4. settings.json に追加します：

"mcp.servers": {
  "africa-energy": {
    "command": "python",
    "args": ["/path/to/africa_energy_mcp/server.py"]
  }
}

保存して Cursor を再起動します。チャットでツールを利用できるようになります。

任意：CI と公開

このサーバーを公開したり自動実行したりする場合（たとえば、リモートホストや CI から実行できるようにする場合）は、Docker イメージをビルドしてレジストリ（GitHub Container Registry または Docker Hub）にプッシュする CI の追加を検討してください。Dockerfile と GitHub Actions ワークフローの例が出発点としてリポジトリに含まれています。ご希望のレジストリやリリースプロセスに合わせて自由にカスタマイズしてください。

ほとんどのユーザーにとって、最も簡単な方法はサーバーをローカルで実行し（上記の「セットアップ」を参照）、Claude Desktop や Cursor などの MCP クライアントに接続することです。

プロジェクト構成

africa_energy_mcp/
├── server.py              # MCP server entry point, wires tools + handlers
├── config.py              # Environment variables, constants, country list
├── api_client.py          # Async HTTP client, retry logic, caching
├── tools.py               # MCP tool schema definitions
├── handlers.py            # Input validation, routing, response formatting
├── requirements.txt       # Python dependencies
├── .env.example          # Example environment configuration
└── README.md             # This file

アーキテクチャ

リクエストの流れ：

1. server.py が MCP 経由でツール呼び出しを受け取ります
2. handlers.py が入力を検証し、api_client.py を呼び出します
3. api_client.py がキャッシュを確認し、HTTP リクエストを送信し、失敗時に再試行します
4. レスポンスがキャッシュされ、JSON として返されます
5. server.py が MCP クライアント向けにフォーマットして返します

キャッシュ：

• キー：(endpoint, frozenset(params))
• TTL：10 分（config.py で設定可能）
• メモリ内のみ（サーバーの再起動時にクリアされます）

再試行ロジック：

• 5xx エラーとタイムアウト時に再試行します
• 最大 3 回試行します
• 指数バックオフ：1s、2s、4s
• 4xx エラー（クライアントエラー）では再試行しません

設定

config.py を編集して調整します：

• REQUEST_TIMEOUT：HTTP タイムアウト（デフォルト：30s）
• RETRY_MAX_ATTEMPTS：最大再試行回数（デフォルト：3）
• RETRY_BACKOFF_FACTOR：バックオフの倍率（デフォルト：2.0）
• CACHE_TTL_SECONDS：キャッシュの有効期限（デフォルト：600s）

ログ

ログは次の形式で stderr に出力されます：

2024-05-16 10:30:45,123 - handlers - DEBUG - Tool call: get_electricity_data for Kenya, year=2022

ログレベル：

• DEBUG：ツール呼び出し、キャッシュのヒット／ミス、再試行の試行
• INFO：API 呼び出しの成功、キャッシュ操作
• WARNING：再試行、期限切れのキャッシュエントリ
• ERROR：API の失敗、検証エラー、ネットワークの問題

エラー処理

すべてのツール呼び出しは、適切にフォーマットされた JSON エラーレスポンスを返します：

{
  "error": "Validation error: Country must be a non-empty string."
}

よくあるエラー：

• Validation error：入力が無効です（国名が不正、年が範囲外など）
• API error：サーバーが 4xx または 5xx を返しました
• Request timeout：API が 30s 以内に応答しませんでした（再試行します）
• Unexpected error：未処理の例外です

テスト

# Start the server
python server.py

# In another terminal, test with curl (mock MCP call):
# This is for manual testing; MCP clients handle this automatically

または、Python でハンドラーを直接テストできます：

import asyncio
from handlers import call_tool
from api_client import APIClient

async def test():
    async with APIClient() as client:
        result = await call_tool(
            "get_electricity_data",
            {"country": "Kenya", "year": 2022},
            client
        )
        print(result[0].text)

asyncio.run(test())

トラブルシューティング

「Unknown or invalid tool」

• Claude Desktop／Cursor を再起動します
• 設定ファイルのパスが正しいことを確認します

「AFRICA_ENERGY_API_KEY not found」

• .env ファイルを作成します（.env.example からコピーします）
• AFRICA_ENERGY_API_KEY が設定されていることを確認します
• 有効な RapidAPI キーであることを確認します

「API error 401」

• API キーが無効か、期限切れです
• RapidAPI ダッシュボードでキーを再生成します

「Request timeout」

• API の応答が遅いため、サーバーが自動的に再試行します
• 再試行を使い切った場合は、config.py の REQUEST_TIMEOUT を増やします

「No such file or directory: server.py」

• africa_energy_mcp ディレクトリから実行します
• またはフルパスを指定します：python /path/to/server.py

コントリビューション

サーバーを改善するには：

1. このリポジトリをフォークします（GitHub 上にある場合）
2. 機能ブランチを作成します
3. handlers.py、api_client.py を変更するか、tools.py に新しいツールを追加します
4. ローカルでテストします
5. プルリクエストを送信します

ライセンス

MIT License — プロジェクトで自由に使用、変更できます。

サポート

問題や質問については：

• MCP ドキュメントを確認します
• RapidAPI Africa Energy API ドキュメントを確認します
• GitHub で Issue を作成します（ホストされている場合）

---

バージョン：1.0.0
最終更新日：2024-05-16
ステータス：本番環境対応 ✅