内容
# sugra-api-mcp
<!-- mcp-name: ai.sugra/api-mcp -->
<p align="center">
<img src="https://app.sugra.ai/images/brand/sugra-app-icon.svg" alt="sugra.ai" width="112" height="112" />
</p>
<p align="center">
<a href="https://pypi.org/project/sugra-api-mcp/">PyPI v0.8.2</a> |
Python 3.11+ |
<a href="https://github.com/Sugra-Systems/sugra-api-mcp/blob/main/LICENSE">MIT</a>
</p>
**让任何 AI 代理都能访问 1,500+ 个跨市场、经济、公司、政府、新闻、气候、航运和实体筛查的数据端点 - 通过一个 MCP 服务器。**
与 ChatGPT、Claude、Gemini、xAI、Cursor、VS Code 和任何 MCP 客户端兼容。
官方 [模型上下文协议](https://modelcontextprotocol.io) 服务器，用于 [Sugra API](https://sugra.ai)：一个连接器、一个捆绑的端点目录和带有来源归属的 structured 工具结果。
## 会话示例
托管的 MCP 转录（此处显示的三个组合工具在托管端点上运行）。捕获的示例 - 措辞和数字因运行而异，并且随着新的 BLS 数据发布而变化：
```text
用户：美国的通货膨胀率目前处于什么水平，过去一年来有何趋势？
解析实体（"美国通货膨胀"）
-> 宏观指标 cpi_us（美国劳工统计局）
获取快照（"cpi_us"）
-> 最新读取结果，包含新鲜度、来源和配额成本
获取时间序列（"cpi_us"，metric="macro_series"，range="1y"）
-> 12 个月度数据点，带有显式降采样标志
代理：美国 CPI 最新发布数据显示同比增长 2.9%，比 12 个月前下降 3.5% - 自春季以来稳步下降。
来源：美国劳工统计局通过 Sugra API 提供。
```
每个工具结果都带有结构化元数据 - 来源归属、新鲜度和速率限制成本，以便代理可以引用来源和预算请求，而不是猜测。
## 工作原理
```mermaid
flowchart LR
A["AI 代理<br/>(ChatGPT, Claude, Gemini, xAI, IDEs)"] --> B["Sugra MCP<br/>托管：11 个工具 / 本地：8 个工具"]
B --> C["Sugra API<br/>1,500+ 端点，36 个数据域"]
C --> D["160+ 主要来源<br/>市场、经济、政府、<br/>新闻、气候、航运"]
```
在网关后面是 Sugra API：160+ 个主要来源 - 主权统计机构、中央银行、政府间机构等 - 提供 1,500+ 个跨 36 个数据域的端点。该服务器提供一个捆绑的完整端点目录，因此发现（搜索、描述、工具集）在本地运行，无需网络调用；只有实际数据请求才会命中 API。
## 托管 MCP（推荐）
无需安装。将您的客户端指向托管的 Streamable HTTP 端点：
```
https://app.sugra.ai/mcp
```
- 11 个工具：八个网关工具加三个组合代理工具（`resolve_entity`、`get_snapshot`、`get_timeseries`）
- 通过 claude.ai 和 ChatGPT 连接器 UI 进行 OAuth 登录，或使用 API 密钥 `Authorization: Bearer sugra_xxx_...`
- 在 claude.ai 中：设置 -> 连接器 -> 添加自定义连接器
- 在 ChatGPT 中：设置 -> 连接器 -> 添加 MCP 服务器
## 本地包
在您的机器上通过 stdio（或自托管 HTTP）使用 API 密钥运行：
```bash
pip install sugra-api-mcp
```
- 八个网关工具
- 用于桌面客户端和 IDE 的 stdio，用于自托管的 Streamable HTTP
- 使用 `SUGRA_API_KEY` 进行身份验证
在 [app.sugra.ai/settings/billing](https://app.sugra.ai/settings/billing) 获取免费 API 密钥（免费层：50 次请求/天）。
## 快速入门
```bash
pip install sugra-api-mcp
export SUGRA_API_KEY=sugra_xxx_... # 免费密钥：app.sugra.ai/settings/billing
sugra-api-mcp call quotes_symbol_price --params '{"symbol":"AAPL"}'
```
通过代理进行相同的调用：连接服务器到您的客户端（下一节），然后询问 "AAPL 当前交易价格是多少？使用 Sugra。" 代理在目录中找到 `quotes_symbol_price` 并使用符号调用它。
## 连接您的客户端
支持的客户端：
- **Anthropic Claude**：Claude Desktop，Claude Code（CLI），claude.ai（网页）
- **OpenAI GPT**：ChatGPT（通过 MCP 连接器）
- **Google Gemini**：Gemini CLI，Gemini Code Assist（VS Code + JetBrains）
- **xAI**：xAI SDK 和 Responses API 中的远程 MCP 工具
- **IDEs**：VS Code（原生），Cursor，Zed，Cline，Continue.dev，Windsurf
- **自定义代理**：任何使用 Python 或 TypeScript MCP SDK 构建的代理
### Claude Desktop（stdio）
添加到 `claude_desktop_config.json`：
- macOS：`~/Library/Application Support/Claude/claude_desktop_config.json`
- Windows：`%APPDATA%\Claude\claude_desktop_config.json`
- Linux：Claude Desktop 没有 Linux 版本。在 Linux 上，使用 `pip install sugra-api-mcp` 并使用 Claude Code（CLI），IDE 客户端或下面的托管 HTTP 端点。
```json
{
"mcpServers": {
"sugra": {
"command": "sugra-api-mcp",
"env": {
"SUGRA_API_KEY": "sugra_xxx_yourkey..."
}
}
}
}
```
重启 Claude Desktop。Sugra 工具出现在工具菜单中。
### Claude Code（Anthropic CLI）
```bash
claude mcp add sugra -- sugra-api-mcp
# 然后设置 sugra-api-mcp 读取的环境变量
export SUGRA_API_KEY=sugra_xxx_...
```
或手动编辑 `~/.claude/config.json`，格式与上面类似。
### Cursor、Zed、Cline、Continue.dev、Windsurf
每个都有一个 MCP 设置文件（通常为 `mcp.json` 或等效文件），其_stdio_配置格式与 Claude Desktop 相同。
### ChatGPT
ChatGPT 通过其连接器 UI 支持 MCP。使用托管的 HTTP 端点（如下所示），因为 ChatGPT 不启动本地_stdio_进程。
### HTTP（claude.ai、ChatGPT、远程代理）
托管的 Streamable HTTP 端点：
```
https://app.sugra.ai/mcp
```
添加到 claude.ai、ChatGPT 或任何 Streamable HTTP MCP 客户端。 使用 `Authorization: Bearer sugra_xxx_...` 进行身份验证。
在 claude.ai 中：设置 -> 连接器 -> 添加自定义连接器。
在 ChatGPT 中：设置 -> 连接器 -> 添加 MCP 服务器。
## 工具参考
当前版本：八个工具表面，带有托管 OAuth 活动验证，适用于 `https://app.sugra.ai/mcp`，以及与 ChatGPT Apps 兼容的 OAuth 工具元数据。诸如 `get_market_price`、`get_macro_indicator` 和 `get_news` 之类的精选工具名称不属于此包。该包仅公开八个工具：
| 工具 | 用途 |
|---|---|
| `fetch_data` | 一步操作：为自然语言查询找到最佳端点并调用它。 在一次往返中组合搜索 + 调用。 |
| `search_endpoints` | 搜索捆绑的端点目录。 运行时搜索不会获取 `/openapi.json`。 |
| `describe_endpoint` | 检查端点（`operation_id`），包括路径、方法、参数、所需输入、`agent_hints` 和 JSON 正文 POST 操作的 `request_body_schema`。 |
| `call_endpoint` | 按 `operation_id` 调用 Sugra API 操作。 不再支持任意路径调用。 |
| `list_toolsets` | 列出具有端点数量和描述的目录组。 |
| `list_sources` | 显示捆绑的目录源元数据。 |
| `sugra_entity_screen` | 将名称与制裁和观察名单（Sugra Entity）进行筛查。 |
| `sugra_entity_lookup` | 通过标识符进行组合实体查找 - `anchor` 为 `lei` 或 `vat`，以及标识符 `value`；返回注册身份 + 筛查（Sugra Entity）。 |
`call_endpoint` 和 `fetch_data` 都支持使用 `limit`、`fields` 和 `include_raw` 进行响应塑形。塑形适用于包装（`{"data": ...}`）和无包装有效载荷；`fields` 条目可以使用点路径进入嵌套对象（`geo.city`），`meta.shaped` 报告实际应用的内容（`fields_applied` / `fields_unmatched`、`limit_applied`），而不是回显请求。
`describe_endpoint` 返回每个端点的计算 `agent_hints`，以便代理可以在调用前估算时间和并行度：
- `duration_class` - `fast`（约 2 秒，基于快照）、`slow`（实时上游代理，偶尔 15 秒以上）或 `heavy`（每项上游工作，大批量可能超过网关超时）
- `max_concurrency` - 单个会话的建议上限并行调用
- `bulk_cost` - 在每项批量端点上：每个请求体中的项目 1 个请求积分（API 在 `X-RateLimit-Cost` 响应头中报告总数）
### 仅限托管代理工具（app.sugra.ai/mcp）
托管的 MCP 端点 `https://app.sugra.ai/mcp` 提供相同的八个工具 **加** 三个组合代理工具，这些工具在_stdio_或自托管安装中不可用：
| 工具 | 用途 |
|---|---|
| `resolve_entity` | 免费文本（股票代码、公司、指标、硬币、货币对）到规范的市场或宏观实体。 模糊匹配返回排名的候选项，从不进行无声选择。 |
| `get_snapshot` | 实体加命名配方到一个组合的当前视图，包含新鲜度、来源、覆盖范围和计费块。 组合调用收取固定配方成本（1-2 个请求）从每日配额中扣除。 |
| `get_timeseries` | 实体加指标（`price`、`macro_series`、`etf_flows`）到一个有显式降采样标志的有界序列。 |
这三个工具包装了一个内部组合层，需要托管部署中可用的基础设施凭证。 工具代码包含在包中，但仅在托管 HTTP 入口点注册，并且仅在存在该凭证时 - `pip install sugra-api-mcp`（stdio 和自托管 HTTP）始终公开经典的八个工具网关。 任何文档中的托管示例均标有此类标签。 对于合规性实体查找（LEI / VAT，制裁筛查），使用 `sugra_entity_lookup` 和 `sugra_entity_screen`，它们在每个传输上都有效。
## CLI
服务器启动保持不变：
```bash
sugra-api-mcp
sugra-api-mcp --transport streamable-http --port 8001
```
目录和网关帮助程序：
```bash
sugra-api-mcp doctor
sugra-api-mcp list-toolsets
sugra-api-mcp search "NASDAQ futures"
sugra-api-mcp describe cot_financial
sugra-api-mcp call quotes_symbol_price --params '{"symbol":"AAPL"}'
```
## 环境变量
| 变量 | 必需 | 默认值 | 描述 |
|---|---|---|---|
| `SUGRA_API_KEY` | 是（stdio） | - | 您的 Sugra API 密钥。 在 HTTP 模式下，此密钥成为没有 Bearer 的请求的后备。 |
| `SUGRA_API_BASE` | 否 | `https://sugra.ai` | 自托管或测试环境覆盖。 |
| `SUGRA_TIMEOUT` | 否 | `30` | 请求超时（秒）。 |
| `SUGRA_MCP_ALLOWED_HOSTS` | 否（HTTP） | - | 允许在反向代理后面的逗号分隔主机名列表。 |
| `SUGRA_MCP_ALLOWED_ORIGINS` | 否（HTTP） | chatgpt.com, claude.ai, cursor.sh + 其他 | 浏览器基 MCP 客户端的逗号分隔允许来源列表。 同时适用于外部 Starlette CORS 层和内部 FastMCP DNS 绑定源检查，因此两者保持同步。 `*` 完全禁用内部源检查（仅限自托管/开发）；Bearer 身份验证仍然控制工具调用。 |
### 带有 OAuth 的 HTTP 传输
当使用 `--transport streamable-http` 运行服务器时，允许未经身份验证的 MCP 发现请求（`initialize`、`notifications/initialized`、`tools/list`、`resources/list`、`prompts/list` 和 `ping`），以便 ChatGPT Apps 和其他混合身份验证客户端可以发现工具元数据。 为主要 MCP 客户端（ChatGPT、Claude、Cursor）启用 CORS；使用 `SUGRA_MCP_ALLOWED_ORIGINS` 覆盖允许列表。 工具调用仍然需要 `Authorization: Bearer ...`。 接受两种令牌格式：
- 原始 API 密钥（`sugra_...`）- 作为下游 `x-api-key` 传递。 与早期本地 API 密钥设置兼容。
- OAuth JWT - 签名通过发行者的 JWKS 验证。 受众必须与 `https://app.sugra.ai/mcp` 匹配，令牌必须包含 `sugra:read`，并且托管访问在解析用户的 primary API 密钥之前会针对 APP 进行验证。 成功的主持 OAuth 请求会更新 APP 中的 MCP 连接活动。
| 变量 | 必需 | 默认值 | 描述 |
|---|---|---|---|
| `SUGRA_APP_URL` | HTTP + OAuth | `https://app.sugra.ai` | 授权服务器的基本 URL |
| `SUGRA_JWKS_URL` | 否 | `$SUGRA_APP_URL/oauth/jwks.json` | JWKS 端点 |
| `INTERNAL_API_TOKEN` | HTTP + OAuth | - | 用于授权服务器上的用户查找和 MCP 活动端点的共享密钥。 必须在 MCP 进程和 app.sugra.ai Laravel 进程上设置相同的值。 |
## 超时和错误合约
`SUGRA_TIMEOUT` 限制了此服务器到 Sugra API 的每个下游 HTTP 调用（默认 30 秒）。 它是较长链条中的一个环节；当工具调用失败时，错误负载中的 `elapsed_ms` 告诉您是哪一个环节导致了超时：
```
MCP 客户端（代理程序） 本地工具超时，通常 60-180 秒，客户端控制
-> 托管代理（app.sugra.ai） 86400 秒，有效期无限
-> 此服务器（httpx） SUGRA_TIMEOUT，默认 30 秒
-> Sugra API -> 上游 15-60 秒每个上游调用，服务器端
```
工具失败返回结构化 JSON 而不是引发异常，以便代理可以选择重试策略：
| `error` 值 | 含义 | 重试策略 |
|---|---|---|
| `upstream_timeout` | 在 `SUGRA_TIMEOUT` 内无响应（`elapsed_ms` 接近 `timeout_s` x 1000） | 重试一次：中止尝试通常在服务器端完成并预热上游缓存。然后缩小请求（较小批次，更严格过滤）。然后重试。 |
| `upstream_connect_error` | 无法到达 Sugra API（DNS 故障，连接被拒绝） | 短延迟后重试。 |
| `upstream_transport_error` | 连接在请求中途断开 | 重试一次。 |
| 自由文本字符串 + `status_code` | API 以 HTTP 4xx/5xx 响应；如果 API 发送 Retry-After 头，则包含 `retry_after` | 遵循 `retry_after` 以获取 429/503；修复请求以获取 4xx。 |
| `tool_execution_failed` | 网关内意外失败（包含 `exception_type`） | 如果持续出现，请报告。 |
所有错误负载都带有 `elapsed_ms`。 `url` 存在于传输和 HTTP 错误中（而非 `tool_execution_failed`，它可能在 URL 存在之前触发）。 在比较 `status_code` 数值时，应考虑这一点；应保护数字比较 `status_code` 以防止这种情况发生。 如果工具调用失败，而是出现普通的客户端消息和没有结构化 JSON，则超时在您的代理程序中触发：提高客户端的工具超时，而不是 `SUGRA_TIMEOUT`。
## 示例
问克劳德：
- “在 Sugra 端点中搜索 NASDAQ 期货。”
- “描述 `cot_financial` 操作。”
- “调用 `quotes_symbol_price`，符号为 AAPL，仅返回符号和价格。”
- “列出可用的 Sugra 工具集。”
## 故障排除
**`SUGRA_API_KEY 环境变量是必需的`**
服务器找不到您的 API 密钥。根据您的运行方式：
- 作为客户端的 MCP 工具（Claude、ChatGPT、Gemini、xAI、IDE 等）：检查 MCP 配置文件中的 `env` 块。值应为类似 `sugra_ao1_...` 的完整密钥，而不是空值或额外引号包装。
- Shell / CI：`export SUGRA_API_KEY=sugra_...` 在运行 `sugra-api-mcp` 之前。
- HTTP 模式：通过 `.env` 或 systemd `EnvironmentFile` 设置，而不是 shell。
**工具响应中的 `401 Unauthorized` 或 `403 Forbidden`**
密钥被接受但被拒绝。常见原因：
- 密钥在 [app.sugra.ai/settings/billing](https://app.sugra.ai/settings/billing) 中重新生成，而您的配置仍保留旧密钥。
- 拼写错误 - 密钥仅包含小写字母和数字，无空格，无尾随换行符。
- 免费层被停用。 登录以验证状态。
**`429 Too Many Requests`**
达到您计划的每日限制。响应头包括 `X-RateLimit-Reset`，带有 UTC 时间戳，指示计数器何时重置（UTC 午夜）。在 [app.sugra.ai/settings/billing](https://app.sugra.ai/settings/billing) 升级您的计划。
**`Invalid Host header`** （仅限自托管 HTTP 模式）
FastMCP 具有 DNS 绑定保护。 将 `SUGRA_MCP_ALLOWED_HOSTS` 设置为反向代理服务的可公开访问主机名逗号分隔列表。 示例：`SUGRA_MCP_ALLOWED_HOSTS=mcp.example.com,example.com`。
**工具结果因 `meta.truncated` 通知而被截断**
一些端点返回非常大的有效载荷（全球野火，全表目录）。客户端强制执行 MCP 25k 令牌限制 - 当达到限制时，数据列表将被修剪，并在 `meta.truncated.retry_hint` 中出现重试提示。添加更严格的过滤器（国家/地区，日期范围，`limit`）以获取完整结果。
**`Python version 3.11 or higher is required`**
sugra-api-mcp 需要 Python 3.11+。检查：`python --version`。如果您有 3.10 或更旧版本：
- Ubuntu：从您的发行版软件包或 deadsnakes PPA 安装 Python 3.11 或更新版本。
- macOS：`brew install python@3.11`
- Windows：从 [python.org](https://www.python.org/downloads/) 下载。
然后重新创建您的虚拟环境。
**托管的 `app.sugra.ai/mcp` 返回 5xx**
托管的端点在部署后可以短暂重启。等待 60 秒，然后重试。如果持续出现，请发送电子邮件至 support@sugra.systems。
**本地调试工具调用**
使用_stdio_运行并记录 JSON-RPC 消息：
```bash
SUGRA_API_KEY=sugra_... sugra-api-mcp 2>&1 | tee mcp-debug.log
```
从第二个终端使用 `nc` 或 MCP 检查器发送手动 JSON-RPC。
## 开发
```bash
git clone https://github.com/Sugra-Systems/sugra-api-mcp
cd sugra-api-mcp
pip install -e ".[dev,http]"
export SUGRA_API_KEY=sugra_...
python -m sugra_api_mcp # stdio 模式
python -m sugra_api_mcp --transport streamable-http --port 8001 # HTTP 模式
python scripts/build_endpoint_catalog.py # 从 sibling API openapi.json 重建捆绑目录
```
运行测试：
```bash
pytest
```
## 许可证
MIT © 2026 Sugra Systems, Inc.
MCP 配置
以下是此 MCP Server 的配置信息，可直接复制到 Cursor 或其他 MCP 客户端中使用。
mcp.json
连接信息
猜你喜欢
暂无推荐服务器