stockdata-mcp

用于股票研究的 MCP 服务器。两个后端，一套工具接口。

这种拆分是有意为之。Qualtrim 是 FMP 的客户：它购买原始数据并叠加一层。因此本服务器对一切原始数据直接访问 FMP，仅在 Qualtrim 独有的内容上消耗 Qualtrim 调用。

52 个工具 — 30 个 FMP，22 个 Qualtrim。

在启用 Qualtrim 后端之前

本服务器的 FMP 半部分是普通的：一个有文档的公共 API，一个你注册获取的密钥，随你怎么用。

Qualtrim 半部分则不是。Qualtrim 不发布 API — 那些路由是从它们随产品发布的 JavaScript 中读出来的，而且它们的服务条款既禁止对平台进行逆向工程，也禁止在未事先获得书面同意的情况下使用自动化手段从中检索数据。

该同意不可转让，本仓库也不授予此同意。如果你想运行 Qualtrim 后端，你需要自己的付费 Qualtrim 账户，以及自己从 Qualtrim 获得的书面许可，由你自己取得。请直接向 support@qualtrim.com 询问。

如果没有这些，请在未设置 QUALTRIM_USERNAME/QUALTRIM_PASSWORD 的情况下运行服务器。FMP 工具单独就能正常工作，这里没有任何东西依赖 Qualtrim。

发布这些代码是作为此类客户端如何构建的参考，而不是邀请你把它指向别人的服务。Qualtrim 声明的违规补救措施是终止账户，而且他们的费用不予退还。

安装

cd ~/Projects/stockdata-mcp
uv venv && uv pip install -e .
./scripts/set-credentials.sh          # prompts; password input is hidden

set-credentials.sh 以 0600 权限写入 .env。它已被 .gitignore 忽略。在 https://site.financialmodelingprep.com/developer/docs 获取免费的 FMP 密钥。

注册一次，即可用于机器上的每次会话：

claude mcp add stockdata --scope user -- ~/Projects/stockdata-mcp/.venv/bin/stockdata-mcp

无需 -e 标志 — 服务器自己读取 .env，因此凭据不会进入 ~/.claude.json。真实的环境变量仍然会覆盖该文件，所以如果你愿意，MCP 客户端也可以传递 -e。

可以从任何会话用 backend_status 检查。

给模型的指导

服务器通过 MCP 协议自带使用说明 — 后端选择、免费层级限制、Qualtrim 的怪癖、如何报告数字。每个 MCP 客户端都会自动收到这些，无需额外设置。

在 .claude/skills/stock-research/ 还有一个更完整的技能，更深入地涵盖研究工作流程。Claude Code 从 ~/.claude/skills/ 读取它（将其符号链接到那里）。Claude Desktop 在自己单独的位置管理技能，不会从该目录读取 — 它依赖上面的服务器说明，其中包含决策关键部分。

缓存与预算

响应缓存在 ~/.cache/stockdata-mcp/cache.db 的 SQLite 存储中。该存储是全局的，而非按客户端 — 该用户的每个服务器进程都打开同一个文件，因此 Claude Code 和 Claude Desktop 共享同一个缓存和同一个每日总量。这是正确性所必需的，而不仅仅是为了效率：FMP 配额属于该 API 密钥，而两个应用使用同一个密钥。

TTL 按端点选择。报价的缓存保留一分钟；公司资料一周；参考数据一个月。日期范围在今天之前结束的历史K线永不过期，因为已经发生的收盘价不可能改变。一直延伸到今天的范围仍然有移动的边界，因此获得 15 分钟。

三个工具管理这些：

estimate_cost 之所以存在，是因为工具与请求的比例不是 1:1，而且从调用方一侧看不到：fmp_search 发出 2 个请求，fmp_price_target 发出 3 个，而 fmp_quote 在免费密钥上每个代码发出 1 个。它报告最坏情况下的请求数、已命中的缓存子请求数，以及相对于今日剩余预算的净值。已验证：在一个包含五次调用的混合计划中，其预测与实际花费完全一致；同一计划热重跑时返回 0。

对六个独立进程并发请求同一代码的情况进行测量：1 次上游请求，5 次缓存命中，无锁竞争。

Related MCP server: StocksMCP

配置

FMP 工具

搜索与参考：fmp_search、fmp_profile、fmp_quote、fmp_peers、fmp_reference。

基本面：fmp_income_statement、fmp_balance_sheet、fmp_cash_flow、fmp_key_metrics、fmp_ratios、fmp_financial_growth、fmp_financial_scores、fmp_revenue_segmentation、fmp_enterprise_values。

分析师与估值：fmp_analyst_estimates、fmp_price_target、fmp_grades、fmp_dcf。

事件与市场：fmp_dividends、fmp_earnings、fmp_earnings_calendar、fmp_historical_prices、fmp_technical_indicator、fmp_screener、fmp_market_movers、fmp_sector_performance、fmp_insider_trading、fmp_news。

fmp_request(endpoint, params) 可达 FMP 约 250 个稳定端点中的任何一个 — ETF 持仓、13F、参议院交易、经济指标、SEC 文件、业绩会记录 — 无需专用封装。

免费层级实际覆盖了什么

用真实的免费密钥验证：29 个工具中有 22 个可用。

需要付费计划：fmp_screener、fmp_reference、fmp_news、fmp_insider_trading、fmp_technical_indicator。每个都会返回一个明确的错误，将计划列为原因。

两点说明：

• 多代码 fmp_quote 会回退到逐代码请求，因为批量路由是付费的。上限为 20 个代码以保护每日配额。

• fmp_technical_indicator 是付费的，但很容易绕过 — fmp_historical_prices 是免费的，因此可以在本地从 OHLCV 计算指标。

免费层级大约允许 250 个请求/天。请传递 limit 和 from_date/to_date；价格历史的默认值是整个序列。

Qualtrim 工具

按代码：qualtrim_overview、qualtrim_profile、qualtrim_quote、qualtrim_dcf、qualtrim_kpi_charts、qualtrim_chart、qualtrim_ai_analysis、qualtrim_analyst_estimates。

比较：qualtrim_available_kpis、qualtrim_compare。

你的账户：qualtrim_portfolios、qualtrim_portfolio、qualtrim_portfolio_look_through_earnings、qualtrim_portfolio_ai_analysis、qualtrim_portfolio_dividends、qualtrim_watchlists、qualtrim_watchlist、qualtrim_dip_finder、qualtrim_watchlist_valuation_ranges。

逃生舱：qualtrim_request(path)，仅 GET。

写入操作（qualtrim_add_watchlist_stock、qualtrim_add_portfolio_holding）除非 QUALTRIM_ENABLE_WRITES=true，否则拒绝运行。

Qualtrim 认证实际上是如何工作的

它们随产品发布的 bundle 看起来像是 bearer-token 认证 — localStorage 中的 authTokens、Authorization: Bearer。其实不是。登录返回用户对象并设置一个 Express 会话 cookie（connect.sid）；授权普通请求的正是这个 cookie。bundle 的 token 路径只有在它的刷新调用中才会被执行。

这个客户端维护一个 cookie jar，将会话缓存在 ~/.cache/stockdata-mcp/qualtrim-session.json（0600），并在遇到 401 时自动重新登录。

已知漂移

它们部署的后端已经偏离了当初读取路由时所用的 bundle：

两个工具已经在使用可用的变体。随着时间推移，预计还会有更多这样的情况 — Qualtrim 工具返回 404 意味着路由移动了，而不是代码错了。

qualtrim_dcf 返回空不是失败；它意味着你的账户中没有为该代码保存 DCF。

Qualtrim 与其服务条款

Qualtrim 不发布 API。这些路由是从它们随产品发布的 JavaScript 中读出来的。两个后果：

它可能毫无通知地失效。 参见上面的“已知漂移” — 它已经发生过了。

它受到他们条款的限制。 他们的可接受使用条款禁止在未事先获得书面同意的情况下使用自动化手段系统性地从网站检索数据，并另行禁止对平台进行逆向工程。他们的执行手段是终止账户，而且他们的费用不予退还。

同意是可以获得的 — 禁令以同意为条件。请直接向 support@qualtrim.com 询问 Qualtrim，并保留他们的回复。

这里的默认设置是保守的：1 个请求/秒，最多 2 个并发，与浏览器匹配的用户代理，默认 GET，不做批量枚举。请将用量控制在交互式研究的量级。

布局

src/stockdata_mcp/
  server.py     tool definitions for both backends
  fmp.py        FMP stable-API client
  qualtrim.py   Qualtrim cookie-session client
  util.py       throttling, response trimming, .env loading
scripts/
  set-credentials.sh
.claude/skills/stock-research/SKILL.md

非投资建议

数据供你自己研究使用。两个来源都不保证准确性，这里也没有任何内容是买入或卖出的建议。