内容
# 量化洞察 MCP 服务器
<!-- mcp-name: io.github.QuantGist-Technologies/quantgist-mcp -->
[](https://smithery.ai/servers/quantgist/quantgist-mcp)
将 [量化洞察](https://quantgist.com) 的宏观经济事件数据暴露为 **模型上下文协议（MCP）** 工具，以便 Claude 和其他 AI 代理可以查询日历、检查事件接近程度和评估交易安全性 — 所有这些都在对话中。
## 功能描述
服务器注册了 22 个工具，任何 MCP 兼容的客户端（Claude Desktop，Claude Code，自定义代理）都可以调用：
**宏观经济事件**
| 工具 | 描述 |
|------|-------------|
| `get_upcoming_events` | 指定时间范围内即将发生的事件，过滤影响程度 |
| `get_events_range` | 指定日期范围内的事件，可选国家/符号/影响过滤 |
| `get_economic_calendar` | 完整的日宏观日历，从 `/calendar` 分组，按时间，覆盖范围/警告元数据 |
| `get_event_detail` | 通过 ID 获取事件的完整详细信息（实际，预测，之前，符号） |
**盈利能力**
| 工具 | 描述 |
|------|-------------|
| `get_earnings_upcoming` | 所有股票即将公布的盈利报告，EPS/收入估计 |
| `get_earnings_for_ticker` | 单个股票的盈利历史（估计 vs 实际，超出/低于预期，EDGAR 链接） |
| `get_earnings_summary` | 单个股票的超出/低于预期计数和整体超出预期率 |
| `get_earnings_surprises` | 市场上最新的 EPS 超出预期 |
| `get_earnings_season_summary` | 当前盈利季节的指数级总结 |
**市场**
| 工具 | 描述 |
|------|-------------|
| `get_markets_overview` | 主要指数和工具的日终报价（S&P 500，Nasdaq，黄金，石油…） |
**发现与帮助**（只读，无需 API 密钥）
| 工具 | 描述 |
|------|-------------|
| `get_pricing` | 计划，价格和功能门控（免费 → 企业）+ 机器人使用附加组件 |
| `get_limits` | 每个计划的上限：请求配额，历史窗口，数据延迟，WS，看跌期权，速率限制 |
| `recommend_endpoint` | 将自然语言用例映射到最佳 REST 端点 + MCP 工具 |
| `get_status` | 检查 API 可达性和链接公共状态页面 |
| `estimate_usage_cost` | 估计哪个计划适合请求量 + 超出 / 机器人使用附加组件说明 |
**账户**（Webhook，API 密钥，账单）
| 工具 | 描述 |
|------|-------------|
| `get_subscription` | 当前计划，状态和账单周期（只读） |
| `list_webhooks` | 已注册的 Webhook 端点（只读；专业计划） |
| `create_webhook` | 注册 HTTPS Webhook 端点 — 需要确认；签名密钥仅显示一次 |
| `delete_webhook` | 永久删除 Webhook 端点 — 需要确认，破坏性 |
| `test_webhook` | 发送签名合成测试交付以验证您的消费者 |
| `create_api_key` | 创建（可选范围）API 密钥 — 需要确认；密钥仅显示一次 |
| `create_checkout_session` | 为计划升级创建 Stripe Checkout 会话 — 需要确认；**绝不收费** |
### 编写工具和同意模型
变更工具遵循显式人工干预模式：
- **`confirm: true` 是必需的。** 未启用时，变更工具将 **不会调用 API**，并返回将发生的情况的预览，以便代理可以首先获得用户的批准。
- **计费授权。** `create_checkout_session` 绝不收费 — 它返回一个 Stripe 主机 Checkout URL，用户必须在浏览器中打开并完成。付款后计划会自动升级。
- **一次性密钥。** 新的 API 密钥和 Webhook 签名密钥仅返回一次，并带有警告，提示将它们存储在环境变量或密钥管理器中 — 而不是在提交的文件中。
- **服务器端强制执行。** 计划门控（Webhook 需要专业计划）和密钥范围由 QuantGist API 本身强制执行；工具在 403 上显示可操作提示，而不是绕过任何内容。
## 要求
- Python 3.10+（用于本地/标准输入安装 — 不适用于托管服务器）
- QuantGist API 密钥 — 在 [quantgist.com](https://quantgist.com) 获取（免费层：每天 100 次调用）
## 连接到托管服务器（无需安装）
MCP 服务器通过 HTTP 托管在 **`https://api.quantgist.com/mcp`** — 无需安装，无需 Python。任何支持流式 HTTP 传输的客户端都可以通过在 `X-API-Key` 头中发送您的 QuantGist 密钥来连接（多租户：按您的配额计费）。
Claude Code，一条命令：
```bash
claude mcp add --transport http quantgist https://api.quantgist.com/mcp \
--header "X-API-Key: qg_live_YOUR_KEY"
```
任何流式 HTTP MCP 客户端：
```json
{
"mcpServers": {
"quantgist": {
"type": "streamable-http",
"url": "https://api.quantgist.com/mcp",
"headers": { "X-API-Key": "qg_live_YOUR_KEY" }
}
}
}
```
**仅接受 URL 的连接器（例如 ChatGPT）：** 如果您无法设置自定义标头，请在 URL 中放置密钥 — `https://api.quantgist.com/mcp?apiKey=qg_live_YOUR_KEY`（也接受 `Authorization: Bearer <key>`）。如果可能，首选标头，因为 URL 中的密钥可以记录在代理/服务器日志中。
更喜欢自己运行？本地安装（如下）或自行托管 HTTP 服务器 — 请参阅 [DEPLOY.md](DEPLOY.md)。
## 安装
### 选项 A — 从软件包安装（推荐）
```bash
pip install quantgist-mcp
# 或使用 uv：
uv pip install quantgist-mcp
```
### B — 从源代码安装（开发）
```bash
git clone https://github.com/QuantGist-Technologies/QuantGist_MCP
cd QuantGist_MCP
uv sync # 安装所有依赖项到虚拟环境中
uv run quantgist-mcp # 启动服务器
```
## Claude Desktop 配置
定位您的 Claude Desktop 配置文件：
| 平台 | 路径 |
|----------|------|
| macOS | `~/Library/Application Support/Claude/claude_desktop_config.json` |
| Windows | `%APPDATA%\Claude\claude_desktop_config.json` |
| Linux | `~/.config/Claude/claude_desktop_config.json` |
添加 `quantgist` 服务器块（参见 `claude_desktop_config_example.json`）：
```json
{
"mcpServers": {
"quantgist": {
"command": "quantgist-mcp",
"env": {
"QUANTGIST_API_KEY": "qg_live_YOUR_KEY_HERE"
}
}
}
}
```
保存后重启 Claude Desktop。工具将出现在工具列表中。
### 使用 `uv run` 而不是全局安装
如果您不想全局安装，请在 Claude Desktop 中指向 `uv run`:
```json
{
"mcpServers": {
"quantgist": {
"command": "uv",
"args": ["run", "--directory", "/absolute/path/to/Quangist_MCP", "quantgist-mcp"],
"env": {
"QUANTGIST_API_KEY": "qg_live_YOUR_KEY_HERE"
}
}
}
}
```
## Claude Code 配置
添加到您的项目中的 `.claude/mcp_settings.json`（或全局 `~/.claude/mcp_settings.json`）：
```json
{
"mcpServers": {
"quantgist": {
"command": "quantgist-mcp",
"env": {
"QUANTGIST_API_KEY": "qg_live_YOUR_KEY_HERE"
}
}
}
}
```
## 自托管（HTTP 传输）
除了上述标准输入传输外，服务器还可以通过 `quantgist-mcp-http` 入口点运行为托管 HTTP 服务（`GET /health`，MCP 在 `/mcp`）。它接受每个请求的 `X-API-Key` 头（多租户）或服务器端 `QUANTGIST_API_KEY` 环境变量。
```bash
docker build -t quantgist-mcp .
docker run -p 8000:8000 -e QUANTGIST_API_KEY=qg_live_YOUR_KEY quantgist-mcp
curl http://localhost:8000/health
```
有关 Docker、Docker Compose 和 Coolify 部署，请参阅 [DEPLOY.md](DEPLOY.md)。
## 工具参考
### `get_upcoming_events`
返回指定时间范围内的即将发生的事件。
| 参数 | 类型 | 默认值 | 描述 |
|-----------|------|---------|-------------|
| `hours` | integer (1–168) | 24 | 预测窗口（小时） |
| `impact` | high \| medium \| low \| all | high | 影响过滤 |
### `get_events_range`
返回指定日期范围内的事件。
| 参数 | 类型 | 必需 | 描述 |
|-----------|------|----------|-------------|
| `from_date` | ISO 字符串 | 是 | 开始日期/时间 |
| `to_date` | ISO 字符串 | 是 | 结束日期/时间 |
| `country` | 字符串 | 否 | 2 位国家代码（例如“US”） |
| `impact` | 枚举 | 否 | high \| medium \| low \| all |
| `symbol` | 字符串 | 否 | 交易符号（例如“XAUUSD”） |
### `get_economic_calendar`
返回当日按发布时间分组的宏观日历。
| 参数 | 类型 | 默认值 | 描述 |
|-----------|------|---------|-------------|
| `date` | ISO 日期 | 今天（UTC） | 要获取的日期 |
| `impact` | 枚举 | high | 影响过滤 |
### `get_event_detail`
返回一个事件的完整详细信息。
| 参数 | 类型 | 必需 | 描述 |
|-----------|------|----------|-------------|
| `event_id` | 字符串 | 是 | 来自其他工具的事件 ID |
### `get_earnings_upcoming`
返回所有股票即将公布的盈利报告，按报告日期排序。
| 参数 | 类型 | 默认值 | 描述 |
|-----------|------|---------|-------------|
| `limit` | integer (1–100) | 20 | 返回的即将到来的报告数量 |
### `get_earnings_for_ticker`
返回单个股票的盈利历史（EPS 估计 vs 实际，收入，超出/低于预期，EDGAR 链接）。
| 参数 | 类型 | 默认值 | 描述 |
|-----------|------|---------|-------------|
| `ticker` | 字符串 | 必需 | 股票代码，例如“AAPL” |
| `limit` | integer (1–50) | 10 | 返回的历史报告数量 |
### `get_earnings_summary`
返回单个股票的超出/低于预期计数和整体超出预期率。
| 参数 | 类型 | 必需 | 描述 |
|-----------|------|----------|-------------|
| `ticker` | 字符串 | 是 | 股票代码，例如“AAPL” |
### `get_earnings_surprises`
返回市场上最新的 EPS 超出预期。
| 参数 | 类型 | 默认值 | 描述 |
|-----------|------|---------|-------------|
| `limit` | integer (1–50) | 20 | 返回的顶级惊喜数量 |
### `get_earnings_season_summary`
返回当前盈利季节的指数级总结（总报告，整体超出预期率，平均 EPS 超出预期，季节标签）。无参数。
### `get_markets_overview`
返回主要市场指数和工具的日终报价（S&P 500，Nasdaq，道琼斯，黄金，石油等）。无参数。
### `get_subscription`
返回经过身份验证的帐户的计划、状态和账单周期。无参数。只读。
### `list_webhooks`
列出帐户的已注册 Webhook 端点。无参数。只读；Webhook 需要专业计划。
### `create_webhook`
注册 HTTPS Webhook 端点（专业计划）。需要确认：无需 `confirm: true`，它会返回预览并且不会调用 API。签名密钥仅返回一次。
| 参数 | 类型 | 默认值 | 描述 |
|-----------|------|---------|-------------|
| `url` | 字符串（必需） | — | 将接收事件 POST 的 HTTPS URL |
| `events` | 字符串[] | `["*"]` | 事件类型：`economic_release`、`earnings`、`earnings.scheduled`、`earnings.confirmed`、`earnings.reported`、`earnings.surprise`、`news.radar.breaking` 或 `*` |
| `impact_filter` | 字符串[] | — | 仅传递具有这些影响级别的事件，例如 `["high"]` |
| `confirm` | 布尔值 | `false` | 必须为 `true` 才能实际创建 |
### `delete_webhook`
永久删除 Webhook 端点及其交付历史。需要确认且具有破坏性。
| 参数 | 类型 | 默认值 | 描述 |
|-----------|------|---------|-------------|
| `webhook_id` | 字符串（必需） | — | 来自 `list_webhooks` 的端点 ID |
| `confirm` | 布尔值 | `false` | 必须为 `true` 才能实际删除 |
### `test_webhook`
向 Webhook 端点发送签名的合成测试事件，以便您可以验证可达性和 `X-QuantGist-Signature` 验证。
| 参数 | 类型 | 默认值 | 描述 |
|-----------|------|---------|-------------|
| `webhook_id` | 字符串（必需） | — | 来自 `list_webhooks` 的端点 ID |
### `create_api_key`
创建新的 API 密钥，可选范围。需要确认。完整的密钥仅返回一次 — 安全存储。
| 参数 | 类型 | 默认值 | 描述 |
|-----------|------|---------|-------------|
| `name` | 字符串 | `"Agent key"` | 人类可读标签 |
| `environment` | `live` \| `test` | `live` | 生产数据 vs 沙盒 |
| `scopes` | 字符串[] | `["*"]` | 优先使用最少权限：`events:read`、`calendar:read`、`webhooks:manage`、`usage:read`、`watchlists:manage` |
| `confirm` | 布尔值 | `false` | 必须为 `true` 才能实际创建 |
### `create_checkout_session`
为计划升级创建 Stripe Checkout 会话。**绝不收费** — 返回 Stripe 主机 Checkout URL，用户必须打开并完成。需要确认。
| 参数 | 类型 | 默认值 | 描述 |
|-----------|------|---------|-------------|
| `plan` | `starter` \| `pro` \| `team`（必需） | — | 目标计划 |
| `confirm` | 布尔值 | `false` | 必须为 `true`，并且仅在用户明确批准升级后 |
## 示例提示
这些提示在连接后开箱即用：
- “接下来的 4 小时内有哪些高影响事件？”
- “显示今日的完整经济日历”
- “显示本周的高影响美元事件”
- “哪些宏观事件影响 EURUSD 这个星期五？”
- “给我获取事件 ID abc123 的详细信息”
- “哪些公司即将公布盈利？”
- “显示 AAPL 的盈利超出预期率”
- “本季最大的 EPS 超出预期是什么？”
- “给我一个快速的市场概述”
- “我属于哪个计划？”
- “为高影响美元事件设置一个 Webhook 到 https://my-bot.example.com/hooks”
- “为我的回测器创建一个仅限读取的测试 API 密钥”
- “我想升级到 Pro” *(代理为您提供 Stripe Checkout 链接 — 支付始终由您负责)*
## 环境变量
| 变量 | 必需 | 描述 |
|----------|----------|-------------|
| `QUANTGIST_API_KEY` | 是 | 您的 QuantGist API 密钥（`qg_live_...` 或 `qg_test_...`） |
## 开发
```bash
uv sync
uv run quantgist-mcp # 运行 MCP 服务器
uv run pytest # 运行测试（如果存在）
uv run ruff check src/ # 校验
uv run ruff format src/ # 格式化
```
## API 速率限制
免费层允许每天 100 次 API 调用，最多可达 365 天的事件历史记录。每个工具调用会产生 1-2 次 API 调用。在 [quantgist.com/pricing](https://quantgist.com/pricing) 升级以获得更高的限制。
## 许可证
MIT
