QuantGist

QuantGist MCP Server

将 QuantGist 的宏观经济事件数据作为 Model Context Protocol (MCP) 工具提供，让 Claude 和其他 AI Agent 能在对话中查询日历、检查事件临近情况并评估交易安全性。

功能

该服务注册了 22 个工具，任何兼容 MCP 的客户端（Claude Desktop、Claude Code、自定义 Agent）都可以调用：

宏观经济事件

工具	描述
get_upcoming_events	未来 N 小时内安排的事件，可按影响筛选
get_events_range	指定日期范围内的事件，可选按国家/地区、交易品种或影响筛选
get_economic_calendar	从 /calendar 获取全天宏观日历，按时间分组，并附带覆盖范围/警告元数据
get_event_detail	按 ID 获取单个事件的完整详情（实际值、预测值、前值、交易品种）

财报

工具	描述
get_earnings_upcoming	所有股票代码即将发布的财报，附 EPS/营收估算
get_earnings_for_ticker	单个股票代码的财报历史（估算值与实际值、超预期/不及预期、EDGAR 链接）
get_earnings_summary	单个股票代码的超预期 / 不及预期 / 符合预期次数及整体超预期率
get_earnings_surprises	最新财报中全市场最大的 EPS 意外值
get_earnings_season_summary	当前财报季的指数级摘要

市场

工具	描述
get_markets_overview	主要指数和交易品种的日终报价（S&P 500、Nasdaq、黄金、石油……）

发现与帮助（只读，无需 API 密钥）

工具	描述
get_pricing	方案、价格和功能限制（免费 → 企业版）+ Bot Usage Add-On
get_limits	各方案的上限：请求配额、历史数据窗口、数据延迟、WS、观察列表、速率限制
recommend_endpoint	将自然语言使用场景映射到最合适的 REST 端点和 MCP 工具
get_status	检查 API 是否可访问，并提供公开状态页面链接
estimate_usage_cost	估算适合请求量的方案，并说明超额费用 / Bot Usage Add-On

账户（Webhook、API 密钥、账单）

工具	描述
get_subscription	当前方案、状态和账单周期（只读）
list_webhooks	已注册的 Webhook 端点（只读；Pro 方案）
create_webhook	注册 HTTPS Webhook 端点——需确认；签名密钥仅显示一次
delete_webhook	永久删除 Webhook 端点——需确认，且不可撤销
test_webhook	发送经过签名的模拟测试请求，以验证你的接收端
create_api_key	创建（可选限定作用域的）API 密钥——需确认；密钥仅显示一次
create_checkout_session	创建用于升级方案的 Stripe Checkout 会话——需确认；绝不扣款

写入工具与授权模式

会修改数据的工具遵循明确的人工参与流程：

• 必须设置 confirm: true。 如果未设置该参数，会修改数据的工具不会进行任何 API 调用，而是返回将要执行操作的准确预览，让 Agent 先征得用户同意。
• 账单授权要求。 create_checkout_session 绝不会扣款——它会返回由 Stripe 托管的结账 URL，必须由人工在浏览器中打开并完成操作。工具和 QuantGist 的 API 不会接触任何银行卡数据。付款后方案将自动升级。
• 机密仅返回一次。 新 API 密钥和 Webhook 签名密钥仅会返回一次，并会提示将其存储在环境变量或密钥管理器中，切勿放入已提交的文件。
• 服务端强制规则仍然有效。 QuantGist API 本身会强制执行方案限制（Webhook 需要 Pro 方案）和密钥作用域；工具遇到 403 错误时会提供可操作的提示，不会绕过任何限制。

要求

• Python 3.10+（用于本地/stdio 安装，托管服务无需此项）
• QuantGist API 密钥 — 在 quantgist.com 获取（免费额度：每天 100 次调用）

连接到托管服务（无需安装）

MCP 服务通过 HTTP 托管在 https://api.quantgist.com/mcp — 无需安装，也无需 Python。任何支持可流式 HTTP 传输的客户端都可以连接，只需在 X-API-Key 标头中发送你的 QuantGist 密钥（多租户：从你自己的额度中扣费）。

在 Claude Code 中，只需一条命令：

claude mcp add --transport http quantgist https://api.quantgist.com/mcp \
  --header "X-API-Key: qg_live_YOUR_KEY"

任何支持可流式 HTTP 的 MCP 客户端：

{
  "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。

安装

选项 A — 从软件包安装（推荐）

pip install quantgist-mcp
# or with uv:
uv pip install quantgist-mcp

选项 B — 从源代码安装（开发）

git clone https://github.com/QuantGist-Technologies/QuantGist_MCP
cd QuantGist_MCP
uv sync          # installs all dependencies into a venv
uv run quantgist-mcp   # start the server

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）：

{
  "mcpServers": {
    "quantgist": {
      "command": "quantgist-mcp",
      "env": {
        "QUANTGIST_API_KEY": "qg_live_YOUR_KEY_HERE"
      }
    }
  }
}

保存后重启 Claude Desktop。工具将显示在工具列表中。

使用 uv run 代替全局安装

如果不想全局安装，可将 Claude Desktop 指向 uv run：

{
  "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）中添加：

{
  "mcpServers": {
    "quantgist": {
      "command": "quantgist-mcp",
      "env": {
        "QUANTGIST_API_KEY": "qg_live_YOUR_KEY_HERE"
      }
    }
  }
}

自托管（HTTP 传输）

除了上述 stdio 传输外，服务还可以通过 quantgist-mcp-http 入口点作为托管 HTTP 服务运行（GET /health，MCP 位于 /mcp）。它接受每个请求的 X-API-Key 标头（多租户），或服务端环境变量 QUANTGIST_API_KEY。

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。

工具参考

get_upcoming_events

返回未来 N 小时内的事件。

参数	类型	默认值	描述
hours	integer (1–168)	24	向前查看的小时数
impact	high | medium | low | all	high	影响程度筛选条件

get_events_range

返回指定日期范围内的事件。

参数	类型	必填	描述
from_date	ISO string	是	开始日期/日期时间
to_date	ISO string	是	结束日期/日期时间
country	string	否	2 位国家/地区代码（例如 "US"）
impact	enum	否	high | medium | low | all
symbol	string	否	交易品种代码（例如 "XAUUSD"）

get_economic_calendar

返回按发布时间分组的当日宏观日历。此工具调用 GET /v1/calendar?envelope=true，而非范围更广的 /events 数据源，因此不会将一般 财经新闻标题混入已安排的宏观数据发布事件中。

结构化输出保留后端封装：

• events / count / returned_count
• total_count
• coverage
• warnings
• truncated
• schema_version

如果后端响应不完整、已过时、被 MCP 安全上限截断，或缺少必需的日历封装， 工具会在 warnings 中说明情况，且不会回退到 /events。

参数	类型	默认值	描述
date	ISO date	today (UTC)	要获取的日期
impact	enum	high	影响程度筛选条件

get_event_detail

返回单个事件的完整详情。

参数	类型	必填	描述
event_id	string	是	来自其他任意工具的事件 ID

get_earnings_upcoming

返回所有股票代码中即将发布的财报，按发布日期排序。

参数	类型	默认值	描述
limit	integer (1–100)	20	返回的即将发布财报数量

get_earnings_for_ticker

返回单只股票代码的财报历史记录（每股收益预期与实际值、营收、超预期/不及预期情况、EDGAR 链接）。

参数	类型	默认值	描述
ticker	string	必填	股票代码，例如 "AAPL"
limit	integer (1–50)	10	返回的历史财报数量

get_earnings_summary

返回某股票代码的超预期 / 不及预期 / 符合预期次数，以及整体超预期率。

参数	类型	必填	描述
ticker	string	是	股票代码，例如 "AAPL"

get_earnings_surprises

返回最近财报中全市场每股收益超预期幅度最大的记录。

参数	类型	默认值	描述
limit	integer (1–50)	20	返回的每股收益超预期记录数量

get_earnings_season_summary

返回当前财报季的指数级摘要（财报总数、整体超预期率、平均每股收益超预期幅度、财报季标签）。无需参数。

get_markets_overview

返回主要市场指数和工具（标普 500、纳斯达克、道琼斯、黄金、石油等）的日终报价。无需参数。

get_subscription

返回已认证账户的套餐、状态和计费周期。无需参数。只读。

list_webhooks

列出账户注册的 Webhook 端点。无需参数。只读；Webhook 需要 Pro 套餐。

create_webhook

注册 HTTPS Webhook 端点（Pro 套餐）。需确认：如果没有 confirm: true，则仅返回预览，不会调用 API。签名密钥仅返回一次。

参数	类型	默认值	描述
url	string (required)	—	用于接收事件 POST 请求的 HTTPS URL
events	string[]	["*"]	事件类型：economic_release、earnings、earnings.scheduled、earnings.confirmed、earnings.reported、earnings.surprise、news.radar.breaking 或 *
impact_filter	string[]	—	仅传送具有这些影响级别的事件，例如 ["high"]
confirm	boolean	false	必须为 true 才会实际创建

delete_webhook

永久删除 Webhook 端点及其投递历史记录。需确认，且此操作具有破坏性。

参数	类型	默认值	描述
webhook_id	string (required)	—	来自 list_webhooks 的端点 ID
confirm	boolean	false	必须为 true 才会实际删除

test_webhook

向 Webhook 端点发送已签名的合成测试事件，以便验证端点是否可访问，以及 X-QuantGist-Signature 是否通过验证。

参数	类型	默认值	描述
webhook_id	string (required)	—	来自 list_webhooks 的端点 ID

create_api_key

创建新的 API 密钥，可选择限定其作用范围。需确认。完整密钥仅返回一次，请妥善保管。

参数	类型	默认值	描述
name	string	"Agent key"	易于识别的标签
environment	live | test	live	生产数据或沙盒
scopes	string[]	["*"]	建议遵循最小权限原则：events:read、calendar:read、webhooks:manage、usage:read、watchlists:manage
confirm	boolean	false	必须为 true 才会实际创建

create_checkout_session

为套餐升级创建 Stripe Checkout 会话。绝不会扣款——返回由 Stripe 托管的结账 URL，用户必须打开并完成结账。需要确认后才能执行。

参数	类型	默认值	描述
plan	starter | pro | team（必填）	—	目标套餐
confirm	布尔值	false	必须为 true，且只能在用户明确批准升级后设置

示例提示词

连接服务后，这些提示词即可直接使用：

• “接下来 4 小时内有哪些影响重大的事件？”
• “显示今天完整的经济日历”
• “显示本周影响重大的 USD 事件”
• “本周五有哪些宏观事件会影响 EURUSD？”
• “获取事件 ID abc123 的详细信息”
• “哪些公司即将公布财报？”
• “显示 AAPL 的盈利超预期率”
• “本季度最大的 EPS 意外情况有哪些？”
• “快速概览一下市场”
• “我当前使用的是哪个套餐？”
• “为影响重大的 USD 事件设置一个指向 https://my-bot.example.com/hooks 的 webhook”
• “为我的回测程序创建一个只读测试 API 密钥”
• “我想升级到 Pro”（Agent 会提供 Stripe 结账链接——付款始终由你完成）

环境变量

变量	必填	描述
QUANTGIST_API_KEY	是	你的 QuantGist API 密钥（qg_live_... 或 qg_test_...）

开发

uv sync
uv run quantgist-mcp          # run the MCP server
uv run pytest                 # run tests (if present)
uv run ruff check src/        # lint
uv run ruff format src/       # format

API 速率限制

免费套餐每天允许调用 API 100 次，并可查询最多 365 天的事件历史记录。每次工具调用会产生 1–2 次 API 调用。升级请访问 quantgist.com/pricing，以获取更高的调用限额。

许可证

MIT