Africa Energy Data Mcp

非洲能源数据 MCP 服务

一个 MCP（模型上下文协议）服务，可将 非洲能源数据 API 提供为 Claude、Cursor 和其他兼容 MCP 的客户端可用的工具。

查询覆盖全部 54 个非洲国家、时间跨度为 2000–2022 年的电力、能源和经济数据。该服务包含自动缓存（TTL 为 10 分钟）、带指数退避的重试逻辑、输入验证和结构化日志记录。

功能

• 5 个工具：电力数据、能源数据、经济指标、健康检查、国家列表
• 自动缓存：10 分钟内存缓存，可减少 API 调用
• 重试逻辑：发生 5xx 错误或超时时，采用指数退避重试 3 次
• 输入验证：验证国家名称、年份和年份范围
• 结构化日志记录：完整的调试日志输出到 stderr（不会干扰 MCP stdio）
• 可用于生产环境：模块化设计、错误处理、超时管理

设置

1. 克隆或下载此仓库

cd africa_energy_mcp

2. 安装依赖

pip install -r requirements.txt

3. 获取 API 密钥

1. 前往 RapidAPI 上的非洲能源数据 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 环境中运行），可以考虑添加 CI，以构建 Docker 镜像并推送到镜像仓库（GitHub Container Registry 或 Docker Hub）。仓库中包含一个 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 次
• 指数退避：1 秒、2 秒、4 秒
• 遇到 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. Fork 此仓库（如果托管在 GitHub 上）
2. 创建功能分支
3. 修改 handlers.py、api_client.py，或在 tools.py 中添加新工具
4. 在本地测试
5. 提交拉取请求

许可证

MIT 许可证 — 可随意用于你的项目并进行修改。

支持

如有问题或疑问：

• 查看 MCP 文档
• 查阅 RapidAPI Africa Energy API 文档
• 在 GitHub 上提交问题（如果托管于此）

---

版本：1.0.0
最后更新：2024-05-16
状态：可用于生产环境 ✅