Finance MCP

Finance MCP

一个 MCP 服务，让 AI 助手能够读取你的真实券商账户及其周边市场信息；但只有你本人（而非助手）拥有发送订单的唯一按钮。

它提供 38 个工具，涵盖 Webull、Saxo、IBKR、Yahoo Finance、SEC EDGAR、BLS、美联储和 BEA；此外还配有一个 Streamlit 仪表盘，这是唯一的下单途径。工具列表会根据你的券商实际支持的功能进行筛选，因此，不同账户会看到 36 或 37 个工具；即使完全没有券商账户，也能使用其中 28 个工具——这是正常可用的安装状态，并非故障。

助手可以起草订单，但不能下单。 草稿会进入本地队列；发送订单必须先经过券商预览，并由你在仪表盘中点击确认。工具端不存在这条操作路径，因此任何提示词都无法触达它。

每个工具都会向客户端声明自身属性，而不只是告知读者：36 个工具中有 32 个被标注为只读，1 个具有破坏性（cancel_order，用于撤销一笔挂单）。遵循 MCP 注解的客户端可以直接放行价格查询，并拦截唯一一个会将请求发送到市场的调用。

它能以及不能通过你的账户做什么

向一个未知仓库索要经纪账户凭据，是软件领域最难以建立信任的请求，因此答案放在这里，而不是藏在下面四十段文字之后。

• 工具端没有任何执行路径。 不是有门槛，也不是有保护——而是根本不存在。draft_order 会写入本地队列。发送订单需要经纪商预览，以及你在仪表板中点击确认；任何提示词都无法触发这一步。
• 38 个工具中有 28 个从不接触经纪商。 SEC 文件、宏观数据、指标、期权数学、财报。完全没有凭据也能使用这 28 个工具，这样安装就能正常工作，而不是功能受限。
• 三个适配器中有两个从未运行过。 Saxo 和 Interactive Brokers 是根据已发布的 API 参考资料构建的，尚未在实盘或模拟账户上执行。所有使用它们的工具输出都会说明这一点。只有 Webull 曾在真实账户上运行过。
• 仪表板的提交按钮仅支持 Webull。 MCP 工具通过经纪商协议进行路由；但这个按钮目前还不会这样做。
• 如果经纪商提供只读密钥，请使用它。 仪表板之外的任何部分都不需要写入权限。

1,431 项测试，分布在 32 个文件中；CI 会在每次推送时运行它们。

这些测试都会将网络请求替换为模拟，这样做是正确的——如果 SEC 夜间返回 503 就导致测试套件失败，那这样的测试套件就没人会看。也正因如此，有两个缺陷逃过了所有测试：一条欧元区序列在八个月前就停止发布，却仍被报告为最新；一个文件监视器对每个请求都返回 403，却声称运行正常。只有访问真实互联网才能发现这两个问题。tests/test_live_sources.py 会向每个外部数据源发起真实请求，并检查此工具对返回结果的描述是否属实——尤其会检查标记为最新的数据序列是否真的最新。该测试需显式启用，默认跳过：

FINANCE_LIVE_SOURCES=1 pytest tests/test_live_sources.py -v -s

它还会在 CI 中每周运行，因为依赖某人记得去做的检查，最终总会停止执行——而数据序列停更和抓取器损坏，正是那些会在数周内悄然出现的故障。在仓库密钥中设置 FRED_API_KEY 和 SEC_USER_AGENT 之前，该工作流不会执行；如果未设置，它会在作业摘要中明确说明，而不会显示一个看似通过、实际却什么都没验证的绿色勾号。

---

带有叠加指标、成交量窗格和预测锥的蜡烛图。周末和市场假日会被折叠，因此不会出现空白区间。

---

功能

价格	Webull 实时 OHLCV 数据，并以 Yahoo 作为回退；数据经过完整性检查，包括 K 线排序、交易时段内的陈旧程度以及 OHLC 合理性。每个价格都会注明对应的 K 线及其时效。
分析	96 个固定技术指标、包含 POC 和价值区域的成交量分布、Black-Scholes 希腊值和隐含波动率、回测、基于 ATR 感知止损的头寸规模计算、投资组合集中度和相关性。
文件	解析 SEC EDGAR 内容，而非直接转发：包含交易代码和 10b5-1 状态的 Form 4、按条目代码分类的 8-K、13F、13D/G、144、NPORT、内嵌 XBRL。一份 Form 4 的 XML 约有 6,600 个词元；工具会直接返回答案。
宏观	来自 BLS、Fed（标记 FOMC 和点阵图会议）和 BEA（PCE、GDP）的经济日历，每一行都包含已发布的数据或上一期数据，绝不包含预测值。
执行	草拟、经纪商预览、人工批准。交易前检查会阻止裸卖空、核实各币种的购买力，并拒绝经纪商自身规则不允许的订单。

---

所需条件

操作系统	Windows、macOS、Linux。桌面提醒使用各平台自带的通知工具（PowerShell、osascript、notify-send）；如果设备没有通知工具，会明确说明，因而无头服务器不会收到提醒。
安装	执行 uv tool install --with streamlit --with plotly hitl-finance-mcp，然后将客户端指向 finance-mcp 命令。脚本安装程序（install.sh、install.bat）会添加配置模板、注册客户端并创建快捷方式。
Python	3.10 或 3.12，二者均已纳入 CI 覆盖范围。系统会为你安装 uv。
券商	可选。Webull、Saxo 或 IBKR——设置 FINANCE_BROKER。只有 Webull 在真实账户上运行过。若未提供券商凭据，则不会注册账户和订单工具；价格来自 Yahoo，其余 28 个工具均可正常使用。
密钥	SEC_USER_AGENT（联系邮箱，SEC 要求提交文件时提供）以及可选的免费 BLS 密钥。

安装指南 → — 全程约 15 分钟，大部分时间都在等待免费 API 密钥。

这会对真实账户下达真实订单。 共识评分是一种固定权重的启发式方法，在回测中表现不如买入并持有策略，全文均明确标注了这一点。此内容不构成财务建议——完整免责声明和第三方数据条款请参阅 NOTICE.md。

---

券商

券商	状态
Webull	已完成端到端验证——真实订单已起草、预览、提交、观察其待成交状态并取消。
Saxo Bank	未经验证。 根据 Saxo 发布的 OpenAPI 参考资料构建，从未对其 API 实际运行。
Interactive Brokers	未经验证。 根据 Client Portal Web API 参考资料构建，从未对其实际运行。需要本地 Client Portal Gateway。

两个未经验证的适配器都会在使用它们的每个工具输出中说明这一点，并且对于文档未明确的路径，会拒绝操作而不是猜测。

dashboard/broker_protocol.py 是接口；tests/test_broker_conformance.py 会对每个适配器运行相同的测试套件。FINANCE_BROKER=ibkr 用于选择协议和 MCP 工具所使用的适配器。

哪些工具适用于哪些券商

38 个工具中有 28 个与券商无关——指标、期权、SEC 文件、内部人士和机构数据、财报、宏观数据。无论你通过哪家券商清算，它们的工作方式都相同，不过底层的价格现在会在券商提供 K 线数据时改用该券商的数据（见下文）。

其中 8 个是账户和订单工具，它们通过 broker_protocol.py 调用，因此适用于任何声明了所需能力的适配器：

工具	所需能力
get_account_info get_open_positions get_open_orders	accounts positions open_orders
draft_order preview_order cancel_order	buying_power preview_order cancel_order
calculate_position_size get_portfolio_risk	buying_power positions

只有配置的券商能够提供的工具才会注册。 设置 FINANCE_BROKER=saxo 后，cancel_order 根本不会出现在 tools/list 中——Saxo 使用自己的订单 ID 取消订单，并未说明如何将其映射到我们的 ID，因此取消工具只能拒绝请求。无法使用的工具会在每次请求中占用模型上下文，而且会多提供一个错误选项。

没有券商时也遵循同一规则。每个适配器都是延迟构建的，因此列出工具时不会打开套接字——这意味着空的 .env 也能顺利构建一个券商对象，并向无法调用其中任何一个工具的用户提供全部 8 个账户工具。现在，这些工具会在离线状态下检查所需凭据，只有具备凭据时才会注册，因此不配置券商的安装会列出 28 个都能使用的工具，而不是 36 个工具中有 8 个无法使用。对于离线时确实无法确定的情况——IBKR 的 Client Portal Gateway 会在浏览器登录后保留会话，且完全不需要令牌——这些工具仍会注册，因为隐藏一个本来能用的工具，就没人能知道它为何可用。

另外两个工具仅适用于提供这些功能的券商：saxo_corporate_actions（股息、拆股、要约收购及其选择截止日期——三家券商中只有 Saxo 提供这些功能）和 ibkr_market_scanner（直接从交易所扫描，而不是根据 11 次 ETF 价格查询推断板块轮动）。

能力按账户而非券商名称确定，因为必须同时满足以下三项：

capability = what the SDK implements
           ∩ what the regional entity serves
           ∩ what this account is entitled to

只有 Webull 在不同主机上运营 12 个相互独立的地区实体，而市场数据权限还需要按账户单独购买——如果订单簿只返回一个档位，说明订阅的是 L1 数据，而不是缺少端点。dashboard/capabilities.py 会缓存按券商 × 实体 × 账户划分的结果；探测只能撤销能力，绝不会凭空添加能力，并且会记录调用做了什么，而不是为什么调用。根据错误消息推断原因，正是这个文件之前会把参数错误归咎于地区的原因。

宏观数据发布

CPI 会在美东时间 08:30:00 发布。日历会显示已经发布的读数或前一次读数，绝不显示预测值——这里没有共识数据源，市场预期属于许可产品，因此与前一次读数相比的“意外”并不是真正的意外。

在预定发布时间附近，宏观数据缓存会从 6 小时缩短到 3 秒，因此你每次查询时都能获得最新的可用数据。设置 FINANCE_MACRO_WATCH=1 后，后台线程也会在数据发布时获取，因此数据会提前准备好。

不要突发发送请求。BLS 文档规定每 10 秒最多 50 次请求；快速轮询时使用 10 次。更频繁地轮询不会让 BLS 更早发布数据——在发布瞬间突发发送一组相同请求，所有请求返回的仍是同一份过期数据，因为等待的是外部事件，而不是吞吐量。

价格来自你的经纪商

fetch_data 会先尝试已配置的经纪商，再尝试 Yahoo，因此 Saxo 用户会获取 Saxo 的 /chart/v1/charts 数据，IBKR 用户会获取 /iserver/marketdata/history 数据——覆盖服务中的所有价格，而不仅仅是账户工具。此前，即使提供了 Saxo 或 IBKR 凭据，整个价格数据流仍然使用公开备用数据源，这一点并不明显，因为工具仍能正常工作。每当使用备用数据源时，都会始终发出提示。

这两个经纪商的数据流都会在返回前按升序排列。Webull 返回的数据按时间从新到旧排列，且没有任何代码对其排序，因此所有指标都在反向序列上运行，板块热力图也把表现最差的标成领跑者；这种错误可不能再犯一次。

contract_rules() 会获取真实的最小价格变动单位和最小交易数量，rule_violations() 在提供这些规则时会使用它们——这项检查可以发现订单预览价格正常、但下单时被拒绝的情况。

仪表盘的提交按钮仍然仅支持 Webull。 MCP 工具通过协议路由；Streamlit 的审批并提交流程尚未如此处理。要改动它，就得把两个从未在实际运行过的适配器放到唯一经过实际验证的代码路径上。验证要先行——这正是 HELP-WANTED.md 所寻求的帮助。

IBKR 使用的是 Client Portal Web API——纯请求／响应 JSON——而不是 TWS 套接字 API。正因如此，它是一个适配器，而不是重写。它还带来了协议中此前没有的一种经纪商行为：IBKR 可以在下单时返回警告，而不是订单；每条警告都需要确认后才能发送任何内容。客户端库通常会从预设回复表中自动回应这些警告。这个工具则会把警告交给批准订单的人处理，这正是它的意义所在。

需要帮助 → ——花一小时使用 Saxo 模拟令牌或 IBKR 模拟账户，就能弥补验证方面的不足。用于验证的脚本只读取数据；绝不会下单。

---

兼容任何 MCP 客户端

服务中的任何部分都不专属于某一个助手。它通过标准输入／输出使用 MCP，因此任何支持 MCP 的工具都能运行它。安装程序会将其注册到机器上找到的每个客户端；若要手动配置，请将以下内容添加到该客户端的 MCP 配置中：

{
  "mcpServers": {
    "finance": {
      "command": "finance-mcp",
      "args": []
    }
  }
}

客户端	配置位置
Claude Desktop	%APPDATA%\Claude\claude_desktop_config.json
Claude Code	claude mcp add finance -- finance-mcp
Cursor	~/.cursor/mcp.json
Windsurf	~/.codeium/windsurf/mcp_config.json
VS Code	.vscode/mcp.json，或用户级 MCP 设置
其他客户端	该客户端所称的 MCP 配置文件；上述 JSON 是标准格式

仪表盘是独立的 Streamlit 应用，不受你使用哪个客户端的影响。订单审批无论如何都在那里进行。

---

宏观日历与实时申报文件

除了经纪商数据源外，还有四个公开数据源，因此 Claude 不仅能看到价格本身，还能看到推动价格变动的事件。

工具	提供的内容
get_economic_calendar	来自三个数据源的美国预定事件——BLS（CPI、PPI、NFP、JOLTS）、Federal Reserve（FOMC 决议，并标记附带点阵图的决议）和 BEA（PCE、GDP、贸易）——每一行都包含已公布事件的实际值，以及尚未公布事件的前值。
get_updates	自某个时间戳以来的变动：新增 SEC 申报文件、已公布的宏观数据，以及幅度较大的价格变动。无需重新获取所有数据，即可回答“有新消息吗？”
get_macro_data	历史 CPI、核心 CPI、失业率、非农就业人数、PPI 和工资数据，以及环比／同比变化。source="markets" 提供来自 FRED、ECB 和 Bank of England 的政策利率、收益率曲线和金融状况数据。
get_edgar_filings	三种模式的 SEC 申报文件：单家公司的申报文件、所有申报主体的实时动态，或对申报文件正文进行全文搜索。
get_insider_activity	解析后的 Form 3/4/5——谁进行了交易、交易价格、卖出是否依据 Rule 10b5-1 计划，以及建仓情况。forms="144" 提供拟议卖出信息，这些信息会在交易前提交，并包含计划采纳日期。
read_filing	按表格类型提取内容：从 DEF 14A 提取高管薪酬、从 13D/13G 提取封面页、从 8-K 提取新闻稿、从 10-K 提取指定条款（风险因素、MD&A），或执行文本搜索。
get_institutional_holdings	最新的 13F-HR 投资组合，合并了不同管理人申报行中的持仓。source="NPORT" 提供注册基金的月度投资组合，包括 13F 未涵盖的债券和衍生品。

申报文件经过解析，而非直接转发。 分析师想从申报文件中获取的大部分信息，已经是机器可读字段。“那笔卖出是预先安排的吗？”在 Form 4 XML 中对应 <aff10b5One>——一个布尔值。因此，服务会提取信息并直接作答，而不是交付整份文件：一份 Form 4 的原始 XML 约有 6,600 个 token，一份 10-K 则约有 610,000 个 token，是 200k 上下文窗口容量的三倍。get_insider_activity 还会区分真正的交易决策（代码 P/S）和薪酬机制——授予、期权行权以及为缴税而扣留的股票——后者经常被错误报道为“内部人士卖出了 X 美元”。

关于延迟。 EDGAR 的接收时间戳精确到秒，因此一份盈利相关的 8-K（条款 2.02）一经接受便会立即显示。你遇到的延迟来自自己的轮询间隔，而非数据源。get_earnings 使用相同的条款代码来确认哪些季度业绩已实际发布，并标记 Yahoo 仅在估算的未来日期——Yahoo 会将未确定的日期发布为一个时间范围，将已确定的日期发布为单日；格式化后，两者无法区分。

没有市场一致预期数据，并且会明确说明这一点。 市场一致预期是需要授权的产品，没有免费的数据源，因此日历中的所有比较都以前值为基准，并会明确标注。相对于前值衡量的“意外”并不是真正的意外：市场交易的是实际值与预期之间的差距，而这里无法获取的恰恰是预期。

速率与配额处理。 BLS 允许未注册用户每天查询 API 25 次；发布日程页面是普通网页抓取，不会占用该配额。结果会缓存（宏观序列 6 小时、日程 24 小时、申报文件 2 分钟），因此重复调用日历不会产生额外开销。SEC 每秒 10 次请求的上限由客户端强制执行。

规范化处理。 申报人名称和发布文本可能使用不同的文字系统和数字格式。专用处理层会将 Unicode 统一转换为规范形式，将无法分解的拉丁字母合字展开（Ærø → AEro，而非 r），转换非 ASCII 数字，并解析美国、欧洲、瑞士或印度格式的数字——包括 (1,234.56) 这样的会计负数。

获取 BLS 密钥（可选、免费，约 2 分钟）

未注册访问每天最多只能查询 API 25 次。要将上限提高到 500 次：

1. 在 data.bls.gov/registrationEngine 注册 — 密钥会通过回复邮件发送。
2. 将 BLS_API_KEY=<your key> 添加到 .env，然后重启服务。
3. 运行 validate_bls_key 工具，确认密钥已通过验证。

最后一步很重要：密钥输入错误不会报错，而是会静默降回每天 25 次的额度，只有几天后额度耗尽时才会显现。注册后，历史数据范围也会从 10 年延长至 20 年，并返回 BLS 自行计算的百分比变化，服务会用这些数据核对自身的计算结果。

随时使用 get_data_sources 查看每个数据源的配置和剩余配额。

---

征求帮助

有三件事，如果有人花一小时帮忙，胜过我自己花一天：

• 验证 Saxo 适配器。 它依据 Saxo 发布的参考资料编写，从未对接他们的 API 运行过。24 小时模拟令牌免费且无需审批，tests/verify_saxo.py 可在不下单的情况下解答六个待解决问题。
• 验证 IBKR 适配器。 情况相同，而且一个模拟账户就足够。运行 Client Portal Gateway，通过浏览器登录，然后执行 python -m tests.verify_ibkr。它不会提交任何内容 — 只读取数据，并调用 IBKR 自己的非约束性 whatif。→ HELP-WANTED.md
• 在干净的机器上安装。 install.bat 和 install.sh 已通过单元测试和代码检查验证，但从未在全新的操作系统上测试过 — 每位新用户首先接触的，正是这里验证最不充分的路径。

此外也欢迎帮助：IG Markets（REST，结构与 Saxo 类似）。 dashboard/broker_protocol.py 是接口； tests/test_broker_conformance.py 可对任何实现该接口的对象运行。

---

数字的来源

不同数据的可信度各不相同，工具会说明每种数据的类别。

类别	来源	验证方式
价格和 K 线	Webull OpenAPI、Yahoo 备用源	完整性检查：排序、基于交易时段的过时检测、OHLC 合理性
已申报财务数据	SEC EDGAR XBRL	权威来源 — 即申报文件本身，并标注表格类型和申报日期
宏观数据	BLS	官方序列；在注册额度下，将我们的环比/同比数据与 BLS 自行计算的数值交叉核对
第三方基本面数据	Yahoo	若存在可比数值，则与 XBRL 申报文件交叉核对；并报告差异
共识评分	此处计算	固定权重的启发式评分，会明确标注 — 在回测中表现不如买入并持有

get_company_financials 会直接返回申报文件中的数值。Yahoo 与申报文件存在差异时，以申报文件为准，工具也会明确说明。

IV 排名是唯一无法免费获得权威来源的指标：没有公开数据源发布隐含波动率历史记录。因此，服务不会假装能做到这一点，而是在查询期权时，每个代码每天记录一次平值 IV 观测值；当某个代码积累了 30 天的历史数据后，才会报告真实的 IV 排名。在此之前，服务会显示已明确标注的已实现波动率估算值，并注明还需要多少条观测数据。

---

数据完整性

市场数据是一切工作的基础，因此我们会对其进行检查，而非盲目信任。每个价格帧——无论来自哪个数据源——都会在任何工具看到它之前通过同一道关卡：

• 强制执行 K 线排序。 Webull API 返回的 K 线按时间从新到旧排列。系统会将价格帧按时间升序排序并断言这一不变量，因此 .iloc[-1] 始终是最新的一根 K 线。（否则，工具会将窗口中最旧的 K 线报告为当前价格，并在时间顺序颠倒的序列上计算所有指标。）
• 按交易时段衡量数据陈旧程度，使用内置的 NYSE 日历，而非日历日，因为日历日无法区分节假日周末和服务中断。
• 合理性检查会拒绝 NaN 价格和不可能的 OHLC K 线。
• 失败会作为错误处理，而不是文本。 工具会引发真正的 MCP 错误，而不是将 "Error: ..." 作为内容返回，因此失败绝不会被误认为是分析结果。
• 切换数据源时会明确告知。 Webull 数据源故障、由 Yahoo 响应请求时，每个受影响的工具都会说明这一点。

运行 pytest 执行测试套件。整个过程完全离线——无需凭据、无需网络，也不会下单。

---

安装

路径 A——安装程序（Windows，无需 Python）

1. 将此软件包解压到任意位置（例如桌面）。
2. 双击 install.bat。
3. 如果尚未安装，安装程序会安装 uv Python 引擎；在 %APPDATA%\Claude\claude_desktop_config.json 中以 finance 为名称注册服务；写入 .env 模板；并在桌面创建 Finance MCP Dashboard 快捷方式。
4. 填写 .env（参见身份验证）。
5. 重启 Claude Desktop。 服务仅会在启动时读取。

如果 WEBULL_APP_KEY 或 SEC_USER_AGENT 仍为占位值，安装程序会打印 ACTION NEEDED 区块，因此未完成配置的安装不会看起来像已完成。

除 uv 外，不会进行系统级安装；首次运行服务或仪表板时，依赖项会被解析并放入缓存，因此首次启动会比之后的启动更慢。

路径 B — 克隆仓库

没有安装程序，也没有快捷方式。你需要自行配置两个入口。

git clone <repo> && cd finance-mcp
uv venv && uv pip install -e ".[dev,dashboard]"
cp .env.example .env      # then edit it — see Authentication below

MCP 服务（Claude 与之通信）。在 Windows 上，将此配置添加到 %APPDATA%\Claude\claude_desktop_config.json，或在 macOS 上添加到 ~/Library/Application Support/Claude/claude_desktop_config.json，然后 重启 Claude Desktop：

{
  "mcpServers": {
    "finance": {
      "command": "uv",
      "args": ["run", "--with", "pandas", "--with", "numpy", "--with", "fastmcp",
               "--with", "yfinance", "--with", "tabulate", "--with", "lxml",
               "--with", "html5lib", "--with", "webull-openapi-python-sdk",
               "/absolute/path/to/finance_mcp.py"]
    }
  }
}

使用绝对路径，即使在 Windows 上也使用正斜杠。Claude Code 用户也可以改为运行 claude mcp add finance -- uv run /absolute/path/to/finance_mcp.py。

仪表板（你查看的界面）。从仓库根目录运行，而不是从 dashboard/ 运行 — app.py 会根据工作目录解析同级模块和 .streamlit/config.toml，从其他位置启动会导致主题丢失：

streamlit run dashboard/app.py            # inside the venv
# or, without activating anything:
uv run --with streamlit --with plotly --with pandas --with numpy \
       --with yfinance --with lxml --with html5lib --with tabulate \
       --with webull-openapi-python-sdk streamlit run dashboard/app.py

它会在 http://localhost:8501 上打开。添加 --server.port 8899 可更改端口。

它仅绑定到回环地址。 Streamlit 默认不设置 server.address，而未设置并不意味着 localhost — 它会监听所有网络接口。对于此应用，这意味着同一网络上的任何人都可以访问一个已连接实时经纪账户、显示其持仓且带有可用提交按钮的界面。.streamlit/config.toml 将地址固定为 127.0.0.1，而 finance-mcp-dashboard 会传入相同的标志，供安装后旁边可能没有该文件的副本使用。这只是默认设置，并非限制：如果确实要在其他位置提供服务，请自行传入 --server.address；如果这样做，请在其前面部署其他防护，因为这里没有身份验证。

提醒管理器（可选的 Windows Toast 通知）。仪表板会在后台线程中自动启动它；要单独运行：

python -m dashboard.alert_manager

验证安装 — pytest 会离线运行整个测试套件，无需凭据或网络连接：

pytest -q

然后让 Claude 运行 get_data_sources — 它会报告已配置的凭据、可访问的数据源以及剩余配额，不会触及你的账户。check_connection 会专门确认 Webull 会话。

---

身份验证

1. 打开此文件夹中新生成的 .env 文件。
2. 粘贴你的 Webull WEBULL_APP_KEY 和 WEBULL_APP_SECRET。
3. 保存文件。

.env 和 conf/token.txt 已加入 gitignore；SDK 日志在写入时会对凭据进行脱敏 — Webull SDK 会在 ERROR 级别转储完整的签名请求（密钥、HMAC 签名、访问令牌），否则常规的速率限制响应会将这些内容直接写入磁盘。

可选设置

变量	默认值	用途
WEBULL_ENVIRONMENT	prod	prod 是默认值，会交易真实账户——这正是它的用途：该工具用于读取数据，未经你在仪表板中批准，不会有任何订单发出。paper 并非“实时数据、模拟订单”——它会将整个客户端切换到 Webull 的沙盒，包括行情数据；沙盒有自己的应用注册表，因此生产环境密钥在那里会返回 401，无法正常工作。仅在使用 WEBULL_PAPER_APP_KEY/SECRET 排练审批流程时使用。paper（别名 uat、sandbox、simulated）会将每次调用都路由到你所在地区的 Webull 模拟环境，因此可以在不承担任何风险的情况下排练完整审批流程——草拟、预览、批准、提交。仪表板会在品牌标识旁边以及 Execution 标签页中显示 LIVE 或 PAPER。如果你所在地区没有公布沙盒主机，客户端会拒绝启动，而不会回退到生产环境。
WEBULL_PAPER_APP_KEY / WEBULL_PAPER_APP_SECRET	—	可选，仅用于 paper 模式。Webull 的沙盒是独立部署，有自己的应用注册表，因此生产环境密钥在那里会以 401 UNAUTHORIZED 验证失败——已通过实时测试确认。请注册一个沙盒应用并设置这些变量；如果未设置，paper 模式会回退到生产环境密钥，而这会返回 401。
WEBULL_ACCOUNT_ID	(未设置)	固定使用特定账户。如果你的登录账号关联了多个账户，则必须设置——服务不会擅自猜测，以免悄悄交易错误的账户。
WEBULL_MIN_REQUEST_INTERVAL	0.25	Webull API 调用之间的间隔秒数。控制调用节奏可避免列表扫描类工具（行业热力图、自选股扫描）触发速率限制。
WEBULL_MAX_RETRIES	3	受速率限制的调用放弃并回退前的尝试次数。
WEBULL_RETRY_BACKOFF	0.75	HTTP 429 指数退避的基准秒数。
WEBULL_REGION_ID	th	Webull 区域。也决定是否启用 Yahoo 的 .BK 股票代码回退。
SEC_USER_AGENT	(未设置)	EDGAR 工具必需。 SEC 的公平访问政策要求提供包含真实联系地址的描述性 User-Agent，例如 Your Name ([email protected])。如果未设置，请求会在本地被拒绝，而不会匿名发送，以免导致 IP 被封禁。
BLS_API_KEY	(未设置)	可选。不使用密钥时，BLS 每天可查询 25 次；免费密钥可将上限提高到每天 500 次，并解锁更长的历史数据。

---

使用方法

通过助手使用

重启 MCP 客户端，使其加载该服务，然后提出你的需求： “NVDA 的日线走势如何？”、“本周经济日历上有哪些待公布事项？”、“起草一笔以 300 买入 10 股 AAPL 的限价单。” 最后一项会将草稿写入队列，然后停止。

在仪表板中

双击 Finance MCP Dashboard 快捷方式，或在仓库根目录运行 streamlit run dashboard/app.py。共有九个选项卡：

选项卡	用途
Charts	显示带叠加指标的 K 线图、成交量窗格和预测锥形图。拖动可平移，滚动可缩放，双击可重置；拖动单个坐标轴可单独调整其比例。周末和市场假日会折叠，因此不会出现空白区段。
Backtest	在已加载的时间窗口上运行自适应共识规则，并报告 CAGR、夏普比率、最大回撤、盈利因子和敞口。
Journal	Claude 通过 log_journal_entry 记录的投资论点；当记录价格偏离市场价格时会发出漂移警告。
Signals	共识评分背后的四项指标判定，以及得出这些判定的市场状态加权矩阵。
Execution	审批台。见下文。
Portfolio	直接从经纪商获取实时余额、购买力和未平仓头寸及其盈亏，并显示随时间变化的价值图表。头寸标记以其自身货币标注——THB 账户中的 USD 持仓绝不会与账户基础货币相加。
Events	经济日历（BLS、FOMC、BEA），包含每行的实际值或前值；关注列表的 SEC 文件；以及针对文件和价格变动的“自上次以来有何变化”对比。
Alerts	价格、RSI 和 MACD 交叉提醒；管理器会发送 Windows 通知，并标记触发提醒的 K 线。
Data	已加载时间窗口中计算出的所有指标列，按时间从新到旧排列。

Events 选项卡：经济日历中的每行均显示实际值或前值；财报日期标记为已确认、有争议或估算；悬停可预览关注列表中的文件。

Execution 选项卡——提交订单的唯一途径。先通过经纪商预览，然后审批。

右上角的 DISPLAY 可切换视觉主题（默认的 Terminal、Research、Slate）、图表叠加配色和行密度。

Execution 选项卡是唯一可以提交订单的地方。 订单提交经过有意设计的两步流程：1 — 通过 Webull 预览会请求经纪商对订单进行报价（不具约束力），之后才会解锁2 — 审批并提交。经纪商无法预览的订单绝不会发送；提交失败时，草稿会保持待处理状态，而不会被标记为已执行。

3. Claude 能做什么，不能做什么

读取价格、文件、宏观经济数据、你的余额和持仓	可以
将订单草稿写入本地 JSON 文件，并通过经纪商预览	可以
提交订单	不可以 — 提交按钮仅存在于仪表板中，且只有经纪商预览后才会出现

没有任何配置标志可以授予 Claude 提交订单的权限。若要移除这一步中的人工参与，就必须编辑源代码。

---

免责声明：这是一个用于教育和实验性量化研究的开源项目。算法交易涉及重大财务风险。

mcp-name: io.github.Blahaj-gif/hitl-finance-mcp