EcuDataMCP

EcuDataMCP

网站：https://dweskz.github.io/EcuDataMCP/

厄瓜多尔公共数据开放基础设施。 EcuDataMCP 通过统一接口，将 AI 助手、研究人员、记者和软件连接到厄瓜多尔官方数据。

它使用 Model Context Protocol (MCP)，让 Claude、ChatGPT、Gemini 和 Cursor 等兼容客户端能够通过对话或软件搜索、浏览和分析这些数据。

不必再手动浏览政府门户，只需询问：

• “SRI 有哪些税收收入数据？”
• “向我展示 INEC 的健康数据集”
• “办理护照需要满足哪些要求？”
• “预览航空运输数据”

注意： 部分工具的定义、参数和描述由 AI 生成或辅助生成，可能不完整、已过时，或未涵盖底层端点的所有情况。源官方数据发生变化时，工具可能返回不完整结果、拒绝有效参数或出现意外行为。请务必对照链接的来源核实答复，并在将结果用于重要决策前手动检查。

---

项目文档

• docs/ROADMAP.md — 已集成的数据来源及待完成事项。
• docs/RESEARCH.md — 路线图中每一项的依据： 已在线核实的发现、调查过的域名和无果的尝试。
• CHANGELOG.md — 近期发布内容。

---

优势

• 即时访问公共数据：用自然语言提问并浏览厄瓜多尔国家机构的数据，无需浏览门户、下载文件或处理各种格式。
• 将多个来源汇集到一处：开放数据、办事流程、法规、公共采购、风险、统计数据及其他官方来源，都可以通过与 AI 的一次对话访问。
• 无需下载即可预览数据：preview_resource_data 可在内存中解析 CSV/TSV、JSON/GeoJSON、Excel (XLS/XLSX) 和部分压缩文件；query_resource_data 可查询 CKAN DataStore，无需下载完整文件。
• 零阻碍：访问兼容的公共数据源不需要 API key 或特殊权限。
• 兼容任何 MCP 客户端：Claude、ChatGPT、Codex、Gemini、Cursor、VS Code、Windsurf、Le Chat、HuggingChat 等。
• 可用于生产环境：提供 Docker、健康检查、结构化日志，以及兼容 MCP 的 HTTP Streamable 服务。

---

使用场景

面向公民

• 无需浏览 gob.ec，即可查询任何政府办事流程的要求、费用和步骤。
• 按主题（健康、教育、安全、经济）搜索公共数据，并了解各机构发布了哪些内容。

面向记者和研究人员

• 浏览国家目录中的数据集，并直接通过 Claude 或 ChatGPT 预览数据。
• 在一次对话中交叉查询多个机构（SRI、INEC、BCE 和各部委）的信息。
• 快速访问反腐败、预算和公共支出执行数据。

面向开发者

• 通过标准 MCP 协议，将厄瓜多尔开放数据集成到应用中。
• 无需编写抓取或文件解析代码，即可快速搭建仪表板并开展探索性分析。
• 将其用作数据后端，为需要厄瓜多尔相关上下文的 AI Agent 提供支持。

面向公共部门

• 让各机构已发布的数据更易访问和发现。
• 支持机构聊天机器人使用真实、最新的数据回答问题。
• 通过将开放数据直接连接到 AI 工具，展示开放数据的价值。

---

数据来源

此 MCP 将政府数据源整合到一个服务中：

来源	数据
Datos Abiertos y Cuenca en Datos (CKAN)	目录、DataStore 和公开文件
SRI	统计数据集、税收征收数据和 RUC
Gob.ec	办事流程、机构和法规
SERCOP/OCDS	公共采购
SGR e IG-EPN	风险事件、海啸和地震
INEC	ANDA、Ecuador en Cifras、人口普查和统计资源
BCE	BCEData、IEM 和其他公开经济指标
Superintendencia de Compañías	名录、审计师和财务数据
Geografía INEC/DPA	省、县和教区

兼容的公开数据源无需 API key。

---

将聊天机器人连接到 MCP 服务

Claude Desktop

最简单的方式无需启动任何服务：Claude Desktop 会通过 uv 执行 PyPI 软件包。将以下内容添加到配置文件中（macOS 上为 ~/Library/Application Support/Claude/claude_desktop_config.json，Windows 上为 %APPDATA%\Claude\claude_desktop_config.json）：

{
  "mcpServers": {
    "ecuador-datos": {
      "command": "uvx",
      "args": ["ecuador-mcp", "--transport", "stdio"]
    }
  }
}

你也可以将附在每个 release 中的 .mcpb 文件安装为 Claude Desktop 扩展。如果你已在运行 HTTP 服务（参见本地运行），请使用 "command": "npx" 和 "args": ["mcp-remote", "http://localhost:8000/mcp"]。

Cursor

1. 打开 Cursor Settings
2. 搜索“MCP”
3. 添加新的 MCP 服务：

{
  "mcpServers": {
    "ecuador-datos": {
      "url": "http://localhost:8000/mcp",
      "transport": "http"
    }
  }
}

VS Code

将以下内容添加到 mcp.json 文件中（通过命令面板运行 MCP: Open User Configuration）：

{
  "servers": {
    "ecuador-datos": {
      "url": "http://localhost:8000/mcp",
      "type": "http"
    }
  }
}

ChatGPT

适用于付费套餐（Plus、Pro、Team、Enterprise）。

1. 前往 Settings > Apps and connectors
2. 打开 Advanced settings 并启用 Developer mode
3. 前往 Settings > Connectors > Browse connectors，然后点击 Add a new connector
4. 设置 URL：http://localhost:8000/mcp

Claude Code

claude mcp add --transport http ecuador-datos http://localhost:8000/mcp

Codex

codex mcp add ecuador-datos --url http://localhost:8000/mcp

这会将带有 url 的 [mcp_servers.ecuador-datos] 区块保存到 ~/.codex/config.toml。若要通过 stdio 而非 HTTP 使用服务：

codex mcp add ecuador-datos -- uvx ecuador-mcp --transport stdio

Gemini CLI

将以下内容添加到 ~/.gemini/settings.json：

{
  "mcpServers": {
    "ecuador-datos": {
      "httpUrl": "http://localhost:8000/mcp"
    }
  }
}

Le Chat (Mistral)

1. 前往 Intelligence > Connectors
2. 点击 Add connector > Custom MCP Connector
3. 名称：“Ecuador Datos” / URL：http://localhost:8000/mcp

Windsurf

将以下内容添加到 ~/.codeium/windsurf/mcp_config.json：

{
  "mcpServers": {
    "ecuador-datos": {
      "command": "npx",
      "args": ["-y", "mcp-remote", "http://localhost:8000/mcp"]
    }
  }
}

HuggingChat

1. 在聊天中，点击 + 图标 > MCP Servers > Manage MCP Servers
2. 点击 Add Server，名称设为“Ecuador Datos”，URL 设为 http://localhost:8000/mcp

---

本地运行

使用 uvx（从 PyPI 安装）

uvx ecuador-mcp --transport stdio

search_ranking/get_financials 使用本地的 Supercías SQLite 数据库；首次查询需要时会在后台自动构建（下载约 356 MB，耗时 5–10 分钟；该查询会要求重试）。从 PyPI 安装后，数据库会保存在用户数据目录中（Windows 上为 %LOCALAPPDATA%\ecuador-mcp，macOS 上为 ~/Library/Application Support/ecuador-mcp，Linux 上为 ~/.local/share/ecuador-mcp）；ECUADOR_MCP_DATA_DIR 可更改其位置。

使用 Docker（推荐）

该镜像通过 stdio 启动，与任何运行在 Docker 中的 MCP 服务一样：

docker build -t ecuador-mcp https://github.com/DweskZ/EcuDataMCP.git
docker run -i --rm ecuador-mcp

对于 HTTP 服务，docker compose 会设置 MCP_TRANSPORT=http 并要求进行身份验证（MCP_REQUIRE_AUTH=1）：如果没有 MCP_AUTH_TOKEN，进程会因错误而停止，容器则会陷入重启循环。启动前请在环境变量或 .env 中设置令牌：

git clone https://github.com/DweskZ/EcuDataMCP.git
cd EcuDataMCP

# Opción A: token en el entorno (puerto 8000)
MCP_AUTH_TOKEN="$(openssl rand -hex 32)" docker compose up -d

# Opción B: token en .env (docker compose lo lee solo)
cp .env.example .env    # edita MCP_AUTH_TOKEN=... y MCP_REQUIRE_AUTH=1
docker compose up -d

# Con variables personalizadas
MCP_AUTH_TOKEN=... MCP_PORT=8007 LOG_LEVEL=DEBUG docker compose up -d

# Detener
docker compose down

客户端在 POST /mcp 请求中通过 Authorization: Bearer <token> 发送令牌。完整的变量列表以及在 HTTPS 代理后部署的说明，请参阅 docs/DEPLOYMENT.md。

手动安装

需要 Python 3.11+ 和 uv。

git clone https://github.com/DweskZ/EcuDataMCP.git
cd EcuDataMCP

# Instalar dependencias
uv sync

# Copiar variables de entorno
cp .env.example .env

# Iniciar el servidor
uv run main.py

环境变量（最常用的变量；完整列表，包括工具配置、并发数、地理代理以及各数据源的基础 URL，请参阅 docs/DEPLOYMENT.md § 环境变量）：

变量	描述	默认值
MCP_HOST	绑定地址	127.0.0.1
MCP_PORT	服务端口	8000
MCP_TRANSPORT	传输方式：http 或 stdio	http
LOG_LEVEL	日志级别（DEBUG、INFO、WARNING、ERROR）	INFO
MCP_AUTH_TOKEN	/mcp 的可选 Bearer 令牌	空
MCP_REQUIRE_AUTH	没有令牌时拒绝远程启动	0
MCP_RATE_LIMIT_REQUESTS / MCP_RATE_LIMIT_WINDOW_SECONDS	每个客户端/IP 的请求配额	120 / 60
MCP_SSL_CERTFILE / MCP_SSL_KEYFILE	用于直接 TLS 的证书和密钥	空
ECUADOR_MCP_USAGE_LOG	1 表示将每次调用（工具、结果、耗时；绝不记录参数）保存到数据目录中的 usage.jsonl；scripts/usage_report.py 可汇总该文件	空
ECUADOR_MCP_DATA_DIR	Supercías 数据库和 BCE 快照的保存位置	克隆仓库时为 data/；从 PyPI 安装时为用户数据目录

在本地运行 stdio 传输：

uv run python main.py --transport stdio

各工具的详细参考说明请见 docs/TOOLS.md。 BCEData/IEM Agent 的 JSON 契约请见 docs/RESPONSE_CONTRACT.md。

---

端点

端点	描述
POST /mcp	JSON-RPC 消息（客户端 → 服务端）
GET /health	健康检查：{"status":"ok","uptime_since":"...","version":"..."}
GET /usage	自启动以来按工具统计的调用次数、错误数和 p50/p95 延迟

设置 MCP_AUTH_TOKEN 后，POST /mcp 需要提供 Authorization: Bearer <token> 请求头。远程部署时还应使用 MCP_REQUIRE_AUTH=1、HTTPS，以及带有独立 IP 配额的代理。/health 和 /usage 无需身份验证（不会公开参数或用户数据）。 远程部署说明请参阅 docs/DEPLOYMENT.md。

---

使用示例

搜索 SRI 数据

“SRI 有哪些税收数据？”

MCP 将搜索 SRI 的公开数据，并显示带有标题、描述和链接的结果。

查看健康数据

“预览医院数据”

MCP 将下载兼容文件，并以格式化表格显示前几行。

查询办事手续

“获取 RUC 需要哪些条件？”

MCP 将在 gob.ec 门户中搜索，并提供所需条件、办理流程和费用。

按类别浏览

“有哪些数据类别可用？”

MCP 将列出可用的主题类别。

---

架构

Cliente MCP (Claude, ChatGPT, Cursor, etc.)
    │
    ▼ POST /mcp
┌──────────────────────────────┐
│   MCPServer (main.py)        │
├──────────────────────────────┤
│  tools/                      │
│   ├── search_ecuador         │  → CKAN + gob.ec (unificado)
│   ├── search_datasets        │
│   ├── query_resource_data    │  → CKAN DataStore
│   ├── preview_resource_data  │  → CSV / JSON / XLS / XLSX
│   ├── get_category_info      │  → helpers/ckan_client.py
│   ├── search_tramites        │
│   ├── get_institucion_info   │  → helpers/gobec_client.py
│   └── ...                    │
└──────────────────────────────┘

---

许可证

MIT License - 详情请见 LICENSE。

---

贡献

欢迎贡献。协作流程请参阅 CONTRIBUTING.md。