schwab-mcp

schwab-mcp

用对话的方式了解你的券商数据。 用自然语言询问 AI 助手你的持仓、筛选期权价差、根据策略规则审查当天的交易，并获取每日收盘报告。数据成本？每个会话约 6 聪（~$0.005）。

为什么要做这个项目

schwab-mcp 中的数据并非 ThinkOrSwim、OptionAlpha 或 Schwab 自家网页界面无法提供。但这些工具无法提供的是一位个性化交易助手，能够整合：

• 你的实时持仓和账户余额
• 包含希腊值、IV 和 OTM% 的实时期权链
• 你的交易策略规则（最低权利金、RWR 目标、行业集中度限制）
• 市场背景（财报日历、VIX 水平、行业轮动）
• 以上所有信息，并在一次对话中呈现

询问 “你会如何评估我今天的新交易？”，即可根据你的标准获取结构化审查。询问 “有哪些符合我策略、且与当前投资组合均衡的 SPS 候选？”，即可获取考虑行业、财报和 IV 的建议——这些建议基于你的实际持仓，而非泛泛而谈。

AI 负责综合分析，schwab-mcp 则提供数据桥接。你按次使用 Bitcoin Lightning 聪付款——无需订阅、无需 KYC，也不会被供应商锁定。完整的一天，包括晨间报告、晚间报告和后续分析，成本约为 6 聪（< $0.01）。

---

一个多租户 MCP 服务，通过 FastMCP 向 AI Agent 提供 Charles Schwab 券商数据。通过 Tollbooth DPYC™ Lightning 微支付实现变现。通过 Streamable HTTP 提供服务，并直接使用异步 httpx 调用 api.schwabapi.com。

Don't Pester Your Customer™（DPYC™）——面向创业型 Bitcoin 倡导者的 API 变现方案

灵感来自 Norton Juster 创作、Jules Feiffer 插画的《The Phantom Tollbooth》（1961 年）。

DPYC™ 经济模式

DPYC™ 代表 Don't Pester Your Customer。这是一种 API 变现理念 和协议，旨在消除会话中途弹出的付款窗口、 订阅催促页面以及 KYC 带来的阻碍。

工作原理

1. 预充值余额 —— 用户在使用工具之前通过 Bitcoin Lightning 购买额度（api_sats）。每次调用工具都会从余额中静默扣款。不会中断操作，也不会弹出“请升级”窗口。额度会在运营者定价模型设置的 tranche_lifetime 时限后过期。

2. Nostr 密钥对身份 —— 用户通过 Nostr 公钥（npub）进行身份识别，而不是使用电子邮件或密码。每种角色对应一个由用户管理的密钥对。无需填写账户创建表单。

3. 连接上的身份 —— 每次付费工具调用都会提供用户的 npub；连接会证明该身份。持有 nsec 的客户端会为每个请求签名（NIP-98）。不持有密钥的客户端通过 OAuth 连接，并通过 request_npub_proof / receive_npub_proof 一次性证明 npub —— 这是一个人工介入的 Secure Courier 交换流程，由用户在其 Nostr 客户端中批准。此后，连接会在用户选择的时长内保留该 npub，即使 MCP 重启也不受影响。

4. 以 UUID 为键的工具身份 —— 每个工具都是一个 ToolIdentity 对象，其确定性 UUID v5 根据能力名称生成。定价提示来自 category 字段：

   类别	定价提示	用途
   free	0 sats	余额查询、状态查询
   read	1 sat	简单查询
   write	5 sats	多步骤操作
   heavy	10 sats	高成本查询

   实际价格（api_sats）由运营者在 Neon 中通过定价模型动态设置。

5. 失败时回滚 —— 如果下游 API 在扣款后调用失败，系统会通过补偿性分批自动退还额度。用户无需为失败的调用付费。

6. 社会契约 —— DPYC™ 生态系统是一个自愿参与的社区：

   • 公民 —— 使用 API 服务的用户
   • 运营者 —— 运行 MCP 服务的开发者（例如此服务）
   • 管理机构 —— 为运营者认证，并对购买收取少量税费
   • 首位策展人 —— 链条的根节点，负责铸造初始 cert-sat 供应量

工具

经纪服务（付费——需信用额度）

所有付费工具都会提供用户的 npub；连接会证明该身份。

工具	等级	描述
get_brokerage_positions	write	投资组合持仓，自动检测期权价差（牛市看跌价差 / 熊市看涨价差）
get_brokerage_balances	write	现金、购买力、净清算价值、当日盈亏
get_stock_quote	write	一个或多个代码的实时报价
get_market_movers	write	市场指数（$SPX、$DJI、$COMPX）的涨跌幅领先者
get_market_hours	write	股票、期权、债券、期货、外汇市场的交易时段
search_instruments	write	按代码、名称或 CUSIP 搜索金融工具
get_option_chain	heavy	筛选后的期权链，包含希腊值、IV、OTM% 和 OI 阈值
get_price_history	heavy	历史 OHLCV 蜡烛图数据
get_brokerage_orders	heavy	订单历史，支持多腿价差（默认 30 天）
get_brokerage_order	heavy	按 ID 查询单笔订单详情
get_brokerage_transactions	heavy	交易历史——交易、股息、现金变动（默认 30 天）
get_brokerage_transaction	heavy	单笔交易详情

免费

工具	描述
session_status	检查运营者的生命周期状态和就绪情况
service_status	检查此服务的运行状况和配置
begin_oauth	启动 OAuth2 流程——返回 Schwab 授权 URL
check_oauth_status	轮询 OAuth 流程是否已完成且会话是否处于活动状态
get_account_numbers	列出已关联的 Schwab 账户号码和哈希值
request_credential_channel	开启 Secure Courier 通道，通过 Nostr DM 交付凭证
receive_credentials	从加密保险库中获取凭证
forget_credentials	删除保险库中的凭证，以便重新交付
update_patron_credential	添加或更新一项赞助者凭证字段
delete_patron_credential	移除一项赞助者凭证字段
get_patron_credential_fields	列出已存储的赞助者凭证字段名称
check_balance	查看信用余额和使用情况
check_price	调用前预览工具费用
purchase_credits	创建 Lightning 账单以购买信用额度
check_payment	验证 Lightning 付款并为余额充值
restore_credits	从先前已付款的账单恢复信用额度
account_statement	查看账户结单摘要
account_statement_infographic	账户的可视化 SVG 信息图（1 sat）
check_authority_balance	检查运营者在 Authority 的 cert-sat 余额
get_pricing_model	查看当前定价模型
list_constraint_types	列出可用的约束类型和架构
request_npub_proof	通过 Nostr DM 请求 npub 所有权证明；返回其 nonce
receive_npub_proof	将回复接收到此连接中，使其持有该 npub
get_operator_onboarding_status	报告运营者配置的就绪情况
get_patron_onboarding_status	报告赞助者凭证的就绪情况
list_notarizations	列出近期的 Bitcoin 公证记录
get_notarization_proof	为赞助者余额生成 Merkle 包含证明

所有经纪工具均为只读，不会下单。

架构

• 多租户：运营者通过 Secure Courier（service="schwab-operator"）交付 btcpay_host + btcpay_api_key + btcpay_store_id + app_key + secret；每位赞助者通过 OAuth2 浏览器流程进行身份验证。会话以 npub 为键。不在环境变量中存储 Schwab 凭证
• 直接使用 httpx：轻量级 SchwabClient 封装，支持 bearer 身份验证和主动刷新令牌（不使用第三方 Schwab SDK）
• Tollbooth DPYC™：预充值的 Lightning 余额、经 Authority 认证的购买订单，以及用于账本持久化的 NeonVault（Postgres）
• 注册表发现：在运行时从 DPYC™ 注册表解析 OAuth2 收集器 URL（无需 OAUTH_COLLECTOR_URL 环境变量）
• 凭证验证：接收时验证运营者凭证——btcpay_host、app_key 和 secret 必须全部存在，才能存入保险库
• 连接上的身份：使用 npub 密钥签名的请求（NIP-98），或在一次 Secure Courier DM 后持有 npub 的 OAuth 连接。重启后仍然有效；有效时长由赞助者选择。受限工具（仅限运营者使用）要求以相同方式证明运营者的 npub。

---

入门指南

本指南涵盖完整的 Tollbooth 入门流程——从生成 Nostr 身份到进行首次经纪数据调用。适用于 运营者（部署 schwab-mcp 的人员）和 赞助者（通过 Claude.ai 或其他 MCP 客户端使用服务的人员）。

1. 获取 Nostr 身份（npub）

DPYC™ 生态系统中的每位参与者都通过一对 Nostr 密钥进行标识——无需电子邮件、密码，也不会被供应商锁定。

什么是 npub？ 它是 Nostr 协议中的公钥，以 bech32 字符串编码，以 npub1... 开头。与之对应的私钥（nsec1...）保存在你的设备上。npub 可以安全分享——系统通过它识别你的身份。

生成方法：

1. 安装 Oxcart（DPYC™ 工作流首选的 Nostr 客户端；尚未测试其他客户端）
2. 创建账户——应用会自动生成你的密钥对
3. 在应用的个人资料／设置页面找到你的 npub（以 npub1... 开头）

或者，使用 nak 等 CLI 密钥生成器：nak key generate

运营方应为其服务身份单独保留一个 npub，与个人 Nostr 账户区分开。

2. 注册成为 DPYC™ 公民

在购买额度或运营服务之前，你需要向 DPYC™ 社区注册你的 npub：

1. 在 Claude.ai 中（连接 DPYC Oracle 后），调用 how_to_join() 了解公民身份相关信息
2. 按照 Oracle 的说明注册你的 npub

公民身份免费，并让你在整个 Tollbooth 网络中拥有可移植的身份。

3. 运营方须知——设置 BTCPay 商店

运营方通过 BTCPay Server 向赞助者收取 Lightning 付款。你需要：

• 一个 BTCPay Server 实例（自行托管或由你的 Authority 托管）
• 具有创建发票权限的 Store ID 和 API Key

这些凭据会通过 Secure Courier 交付（见第 6 步），无需设置为环境变量。

4. 运营方须知——向 Tollbooth Authority 注册

每位运营方都由 DPYC™ 信任链中的一个 Authority 赞助。Authority 会为你的采购订单提供认证，并收取少量费用（默认 2%）。

1. 在你自己的 Schwab MCP 上，调用 request_adoption(authority_npub=<your Authority's npub>, service_url=<your MCP endpoint>)，并使用运营方的 nsec 为请求签名（NIP-98；Pricing Studio 会为你处理）
2. Authority 的所有者批准请求（approve_operator_request），系统随即创建你的账本条目并配置你的 Neon 数据库
3. 完成后，在你的 MCP 上调用 adoption_status(authority_npub=...)，结果将显示为 provisioned

5. 运营方须知——为你的认证余额充值

在你的服务能够向赞助者发放额度之前，你需要 cert-sats：

1. 在你的 Authority 上调用 authority_purchase_credits(amount_sats=1000)——该操作会返回 Lightning 发票
2. 使用任意 Lightning 钱包支付发票
3. 调用 authority_check_payment(invoice_id="...")——确认结算并为你的余额充值

赞助者从你的服务购买额度时，系统会自动扣除你的 cert-sat 余额。

6. 面向运营者——交付凭证（Secure Courier）

运营者必须注册 Schwab Developer 应用，并通过 Secure Courier 交付 BTCPay 和 Schwab API 凭证。凭证绝不会出现在聊天中。

Schwab Developer 应用使用 app_key 和 secret 作为供应商字段名（这些字段在内部映射到 OAuth client_id 和 client_secret）。在 Schwab 注册的 redirect_uri 不应带有 /callback 后缀——请严格使用注册表中显示的基础采集器 URL。

Secure Courier 是一种人在回路中的交换方式：运营者会在自己的 Nostr 客户端中主动回复。取回凭证后，Relay 会被彻底清空——消息会被消费，而不会留在传输线路上。

1. 调用 request_credential_channel(service="schwab-operator", sender_npub=<operator_npub>)——它会返回一个 nonce，并向你的 Nostr 客户端（Oxcart）发送一条欢迎私信
2. 在 Oxcart 中回复这条私信，内容如下：

   {
     "btcpay_host": "https://btcpay.example.com",
     "btcpay_api_key": "YOUR_API_KEY",
     "btcpay_store_id": "YOUR_STORE_ID",
     "app_key": "YOUR_SCHWAB_APP_KEY",
     "secret": "YOUR_SCHWAB_SECRET"
   }
   

3. 调用 receive_credentials(sender_npub=<operator_npub>, service="schwab-operator", nonce=<that nonce>)——凭证会经过验证（btcpay_host、app_key 和 secret 必须全部提供），然后存入保险库

每次部署只需进行一次此设置。运营者凭证会加密后存储在 NeonVault 中，并在服务重启后保留。

7. 面向用户——购买额度（api_sats）

用户预先充值聪余额，并使用这些余额调用经纪工具——不会因每次请求而中断并要求付款。这正是 Don't Pester Your Customer™ 理念的实践。额度以 api_sats 计价，并在运营者配置的 tranche_lifetime 之后过期。

1. 调用 purchase_credits(amount_sats=500)——返回一张带有结账链接的 Lightning 发票
2. 使用任意 Lightning 钱包（Phoenix、Breez、Zeus 等）支付发票
3. 调用 check_payment(invoice_id="...")——确认结算并为你的余额充值

调用付费工具时，余额会逐渐减少。可随时再次调用 purchase_credits 充值。随时调用 check_balance 免费查看余额。调用 check_price 免费预览任意工具的费用。

8. 面向用户——连接 Schwab 账户

你需要授权 schwab-mcp 读取你的 Schwab 账户：

1. 调用 begin_oauth(npub=<your_npub>) 获取授权 URL
2. 在浏览器中打开该 URL 并登录 Schwab
3. 调用 check_oauth_status(npub=<your_npub>) 确认会话已激活
4. 调用 get_account_numbers(npub=<your_npub>) 列出你的账户及其哈希值
5. 调用 update_patron_credential(npub=<your_npub>, field="account_hash", value=<hash>) 设置你的首选账户

9. 在对话中使用 Schwab 工具

会话激活后，可以直接向你的 AI Agent 提出请求：

• “显示我的持仓”——调用 get_brokerage_positions
• “我的账户余额是多少？”——调用 get_brokerage_balances
• “查询 AAPL 和 MSFT 的报价”——调用 get_stock_quote
• “今天涨幅最大的股票有哪些？”——调用 get_market_movers
• “明天市场开盘吗？”——调用 get_market_hours
• “查找 Berkshire Hathaway 的股票代码”——调用 search_instruments
• “显示下个月的 GLD 期权链”——调用 get_option_chain
• “我最近的订单有哪些？”——调用 get_brokerage_orders
• “显示我上周的交易记录”——调用 get_brokerage_transactions

免费工具始终可用：

• “我的 schwab-mcp 余额是多少？”——调用 check_balance
• “显示我的账户对账单”——调用 account_statement

---

安全

• npub 身份——所有会话均以 Nostr 公钥为键。无需邮箱、用户名或密码。
• 连接上的身份——工具不携带证明参数。持有 nsec 的客户端会为每个 HTTP 请求签名（NIP-98，kind 27235）；OAuth 客户端通过 request_npub_proof / receive_npub_proof 将 npub 证明一次性存入连接，patron 会在其 Nostr 客户端中批准，并自行选择有效时长（最长 30 天）。
• Secure Courier——凭据通过 NIP-44 加密的 Nostr 私信交换。取件后会彻底清空中继；消息不会在传输过程中留存。
• NeonVault——凭据（token_json）和账本状态存储在 Postgres 中，并按运营方隔离数据行。环境变量或聊天记录中不会包含机密。
• 运营方凭据隔离——BTCPay 和 Schwab API 凭据（app_key、secret）通过 service="schwab-operator" 的 Secure Courier 发送，在接收时进行验证，并且绝不会出现在日志或响应中。

故障排除

冷启动 / 首次工具调用失败： Horizon 运行时首次收到请求时可能会冷启动。直接重试该工具调用——服务会在几秒内预热，第二次调用即可成功。

“proof is required”： 调用 request_npub_proof，回复私信，然后调用一次 receive_npub_proof(patron_npub, nonce)。之后，连接便会持有该 npub；后续调用只需传入 npub。有效时长由 patron 选择。MCP 重启后证明仍然有效。

“Insufficient credit balance”： 调用 purchase_credits 充值。使用 check_balance 查看当前 api_sats 余额以及 tranche_lifetime 到期时间。

“Operator credentials not configured”： 这是运营方的设置问题，与 patron 无关。运营方必须完成 Secure Courier 流程（步骤 6），以发送 app_key 和 secret。

凭据生命周期状态： 凭据会依次经历 pending（通道已打开）-> delivered（人工已发送私信）-> vaulted（已取回并验证）。如果 receive_credentials 返回的是生命周期状态而非成功结果，这并非错误，而是在告知你当前所处的流程阶段。请按照响应中的说明操作。

OAuth 令牌已存入保险库： OAuth2 流程成功后，token_json 会持久化到 NeonVault。通过 wheel 的 restore_oauth_session，会话可在服务重启后恢复——该功能会检测令牌是否过期，通过提供方刷新令牌，并将轮换后的令牌对持久化回保险库。如果刷新令牌本身已过期（Schwab：7 天），patron 必须重新运行 begin_oauth。

DPYC™ 社区资源

资源	说明
tollbooth-dpyc	Operator SDK——用于保险库、身份验证、定价、Lightning 和 Nostr 身份的 Python 库
dpyc-community	治理注册表——成员资格、公告、威胁模型、信条和商标
dpyc-oracle	社区服务专员——免费入门指导和成员查询
tollbooth-authority	认证基础设施——Schnorr 签名证书和费用收取
tollbooth-sample	Operator 示例——新建 MCP 服务的标准模板
tollbooth-pricing-studio	iOS 定价模型编辑器和 Operator 控制台
cypher-mcp	付费图谱问答——基于 Neo4j/AuraDB 的命名 Cypher 模板
schwab-mcp	Charles Schwab 券商数据
thebrain-mcp	TheBrain 个人知识图谱
excalibur-mcp	借助 Secure Courier 发布 X (Twitter) 帖子的服务
taxsort-mcp	税务分类，附带 Cloudflare Pages 界面
optionality-mcp	期权分析（券商数据 Operator）
tollbooth-oauth2-collector	OAuth2 回调处理程序（倡导者服务）
tollbooth-shortlinks	URL 缩短工具
goodearth-mcp	面向小型特色作物农场的气候分析
beesknees-mcp	The Bee's Knees——一款付费多人竞速游戏
roastify-mcp	Roastify 咖啡目录和包装设计
ChartRemotely-mcp	通过语音或工具调用，在桌面图表上添加证券
tollbooth-web	面向 DPYC™ Operator 前端的共享浏览器 SDK
DPYC Whitepaper	Tollbooth 架构技术白皮书
The Phantom Tollbooth on the Lightning Turnpike	Tollbooth DPYC™ 的叙事式介绍

---

部署

schwab-mcp 运行于 Horizon。任何 MCP 客户端（Claude.ai、Claude Desktop、Cursor 或你自己的 Agent）都可以连接：

https://schwab-mcp.fastmcp.app/mcp

Patron 身份通过连接传递（使用 NIP-98 签名请求，或通过在 request_npub_proof / receive_npub_proof 后持有 npub 的 OAuth 连接）。Schwab 账户需通过 begin_oauth / check_oauth_status 单独关联。会话以 npub 为键。

Operator 环境变量

必需

变量	说明
TOLLBOOTH_NOSTR_OPERATOR_NSEC	Operator 的 Nostr 私钥——用于身份验证、Secure Courier 私信和审计签名的唯一引导密钥

启动时只需要这个环境变量。经过认证的 Operator 会通过加密 Nostr 私信，从 Authority 引导获取 Neon 数据库 URL——不会从环境中读取 NEON_DATABASE_URL。中继集合来自共享的 dpyc-community 注册表，分 tranche 有效期来自 Operator 的定价模型——两者都不是环境变量。

可选调优

变量	说明
SCHWAB_TRADER_API	API 基础 URL（默认值为 https://api.schwabapi.com）

通过 Secure Courier 提供凭据（不是环境变量）

BTCPay 凭据（btcpay_host、btcpay_api_key、btcpay_store_id）和 Schwab API 凭据（app_key、secret）仅通过 Secure Courier（service="schwab-operator"）传送，在接收时进行验证，并存储在加密保险库中。环境变量或聊天中不会包含任何密钥。

开发

先决条件

• Python 3.12+
• 一个具有 API 凭据的 Schwab Developer 应用
• 用于通过 Secure Courier 传送凭据的 Oxcart Nostr 客户端

安装与测试

uv sync            # or: pip install -e ".[dev]"
uv run pytest tests/ -v

项目结构

schwab-mcp/
  server.py            # FastMCP server, OperatorRuntime, credit gating, domain tool endpoints
  schwab_client.py     # Thin async httpx client — bearer auth + token refresh
  vault.py             # Per-user session management (in-memory cache)
  oauth_flow.py        # OAuth2 authorization code flow (state tokens, exchange, callback)
  settings.py          # pydantic-settings (env vars, .env file)
  models.py            # Pydantic response models
  tools/
    account.py         # Positions, balances, orders, transactions (spread detection)
    market.py          # Quotes, price history, market movers, market hours, instrument search
    options.py         # Option chain retrieval + filtering
  tests/
    test_schwab_client.py  # httpx client, token refresh, URL building
    test_server.py         # Singletons, credit gating, Secure Courier callback
    test_vault.py          # Session management
    test_account.py        # Position, balance, order, transaction parsing
    test_market.py         # Quote + price history formatting
    test_oauth_flow.py     # OAuth2 state tokens and code exchange
    test_options.py        # Option chain filtering

先前技术与署名

本仓库中包含的方法、算法和实现可能是 Lonnie VanZandt 的原创作品，首次发表于 2026 年 4 月。本次公开披露根据美国专利法（35 U.S.C. 102）确立了先前技术。

所有使用、复制或衍生作品都必须遵守本仓库所附的 Apache License 2.0，并按照 NOTICE 文件的要求，正确注明原作者。

如何署名

如果您使用或基于此作品进行开发，请在文档或源代码中注明以下内容：

基于 Lonnie VanZandt 和 Claude.ai 的原创作品
首次发布：2026 年 4 月
来源：https://github.com/lonniev/schwab-mcp
根据 Apache License 2.0 授权

欢迎访问这家面向 Bitcoin 支持者和咖啡爱好者的虚拟咖啡馆：stablecoin.myshopify.com。

专利声明

作者保留就本文所述的新颖方法和系统申请专利保护的一切权利。公开披露本作品确立了 2026 年 4 月的优先权日。根据《美国发明法案》，作者自首次公开披露之日起保留一年的宽限期，可在此期间提交专利申请。

致潜在申请人的说明： 本公开仓库及其完整 Git 历史记录可作为先前技术的证据。任何在本仓库发布日期之后提交、且涵盖实质相似方法的专利申请，都可能依据 35 U.S.C. 102(a) 被判无效。

延伸阅读

雷电收费站上的幻影收费站——关于我们如何从 AI API 的变现中获利，然后退居幕后，完整故事尽在其中。

商标

DPYC™、Tollbooth DPYC™ 和 Don't Pester Your Customer™ 均为 Lonnie VanZandt 的商标。有关使用指南，请参阅 dpyc-community 仓库中的 TRADEMARKS.md。

许可证

Apache License 2.0——详情请参阅 LICENSE 和 NOTICE。

---

因为说到底，收费站从来都不是终点，它始终只是旅程的起点。