Schwab MCP Server

Schwab MCP 服务

一个模型上下文协议（MCP）服务，让 Claude 等 AI 助手能够通过 Schwab 官方 API 安全地访问 Charles Schwab 账户和市场数据。

可以做什么

向 Claude 提问：

• “显示我的 Schwab 账户余额和持仓”
• “获取 AAPL、GOOGL 和 MSFT 的实时报价” -“今天 $SPX 的市场领涨股和领跌股有哪些？”
• “显示 TSLA 的期权链及希腊值”
• “获取我过去 30 天的交易记录”
• “搜索与科技相关的 ETF”
• “查看市场是否开市”

非官方 MCP 服务

这是一个由社区开发的非官方 Charles Schwab TypeScript MCP 服务。它未经 Charles Schwab 批准、认可或认证。该服务按“原样”提供，其功能可能不完整或不稳定。使用风险自负，尤其是在处理金融数据或交易时。

概述

此 MCP 服务充当 AI 助手与 Schwab API 之间的桥梁，提供：

• 安全的 OAuth 身份验证：使用 PKCE 实现 Schwab 的 OAuth 2.0 流程，确保安全身份验证
• 全面的交易工具：访问账户、订单、报价和交易记录
• 市场数据工具：实时报价、价格历史、市场交易时间、领涨股和领跌股，以及期权链
• 账户隐私保护：内置账户标识符清理功能，保护敏感信息
• 适用于企业：部署在 Cloudflare Workers 上，并使用 Durable Objects 管理状态

功能

交易工具

• 账户管理
  • getAccounts：获取包含持仓和余额的所有账户信息
  • getAccountNumbers：获取账户标识符列表
• 订单管理
  • getOrder：按 ID 获取订单
  • getOrders：按状态、时间范围和代码筛选并获取订单
  • getOrdersByAccountNumber：按账号获取订单
  • cancelOrder：取消订单（实验性）
  • placeOrder：下单（实验性）
  • replaceOrder：替换订单（实验性）
• 市场报价
  • getQuotes：获取多个代码的实时报价
  • getQuoteBySymbolId：获取单个代码的详细报价
• 交易历史
  • getTransactions：获取所有账户的交易历史记录，并可按日期筛选
• 用户偏好设置
  • getUserPreference：获取用户的交易偏好和设置

市场数据工具

• 金融工具搜索
  • searchInstruments：按代码搜索证券，并获取基本面和参考数据
• 价格历史
  • getPriceHistory：获取历史价格数据，并可自定义周期和频率
• 市场交易时间
  • getMarketHours：按日期查看市场交易时间
  • getMarketHoursByMarketId：获取特定市场的信息
• 市场领涨股和领跌股
  • getMovers：查找指数（$SPX、$COMPX、$DJI）的市场领涨股和领跌股
• 期权链
  • getOptionChain：获取包含希腊值的完整期权链数据
  • getOptionExpirationChain：获取期权到期日期

前提条件

1. Schwab 开发者账户：在 Schwab 开发者门户 注册
2. Cloudflare 账户：用于部署（Durable Objects 需要 Workers 付费计划）
3. Node.js：版本 22.x 或更高
4. Wrangler CLI：通过 npm 安装（包含在开发依赖项中）

开始使用

快速设置

git clone <repository-url>
cd schwab-mcp
npm install

# Authenticate with Cloudflare (first time only)
npx wrangler login

# Create KV namespace for OAuth token storage
npx wrangler kv:namespace create "OAUTH_KV"
# Note the ID from the output - you'll need it for configuration

# Set up your personal configuration
cp wrangler.example.jsonc wrangler.jsonc
# Edit wrangler.jsonc to:
# 1. Replace YOUR_KV_NAMESPACE_ID_HERE with the ID from above
# 2. Change the name to something unique (e.g., "schwab-mcp-yourname")

# Set your secrets
npx wrangler secret put SCHWAB_CLIENT_ID      # Your Schwab App Key
npx wrangler secret put SCHWAB_CLIENT_SECRET  # Your Schwab App Secret
npx wrangler secret put SCHWAB_REDIRECT_URI   # https://your-worker-name.workers.dev/callback
npx wrangler secret put COOKIE_ENCRYPTION_KEY # Generate with: openssl rand -hex 32

# Deploy
npm run deploy

配置说明

• wrangler.example.jsonc - 配置模板（已提交到版本库）
• wrangler.jsonc - 个人配置（已加入 Git 忽略，由模板创建）
• .dev.vars - 本地开发密钥（已加入 Git 忽略，可选）

由于 wrangler.jsonc 已加入 Git 忽略，你可以使用个人配置安全地开发和测试，而不必暴露密钥。

详细配置

1. 创建 Schwab 应用

1. 登录 Schwab Developer Portal
2. 创建一个新应用：
   • 应用名称：你的 MCP 服务名称
   • 回调 URL： https://schwab-mcp.<your-subdomain>.workers.dev/callback
   • 应用类型：根据使用场景选择个人或第三方
3. 记下你的 App Key（客户端 ID），并生成一个 App Secret

2. 设置环境变量

需要设置与快速设置中相同的密钥（见上文）。

GitHub Actions 部署

如需自动部署，请添加以下 GitHub 仓库机密：

1. CLOUDFLARE_API_TOKEN：你的 Cloudflare API 令牌
2. OAUTH_KV_ID：你的 KV 命名空间 ID

推送到 main 时，工作流会处理验证和部署。 Cloudflare 密钥仍需通过 wrangler secret 设置。

使用 Inspector 测试

使用 MCP Inspector 测试你的部署：

npx @modelcontextprotocol/inspector@latest

输入 https://schwab-mcp.<your-subdomain>.workers.dev/sse 并连接。系统会提示你 使用 Schwab 进行身份验证。

使用方法

Claude Desktop 配置

1. 使用 Claude 集成

1. 前往 Claude Desktop 设置
2. 点击“集成”选项卡
3. 点击“添加自定义集成”按钮
4. 输入集成名称“Schwab”
5. 输入 MCP 服务 URL： https://schwab-mcp.<your-subdomain>.workers.dev/sse
6. 点击“添加”按钮
7. 点击“连接”，Schwab 身份验证流程将开始。

2. 将 MCP 服务添加到 Claude Desktop 配置

将以下内容添加到 Claude Desktop 配置文件：

{
	"mcpServers": {
		"schwab": {
			"command": "npx",
			"args": [
				"mcp-remote",
				"https://schwab-mcp.<your-subdomain>.workers.dev/sse"
			]
		}
	}
}

重启 Claude Desktop。首次使用 Schwab 工具时，浏览器窗口将打开以进行身份验证。

命令示例

连接后，你可以向 Claude 提出以下请求：

• “显示我的 Schwab 账户余额”
• “获取 AAPL 的报价”
• “$SPX 今天有哪些市场异动？”
• “显示 TSLA 的期权链”
• “获取我上周的近期交易记录”

本地开发

进行本地开发时，请创建 .dev.vars 文件（git 会自动忽略此文件）：

SCHWAB_CLIENT_ID=your_development_app_key
SCHWAB_CLIENT_SECRET=your_development_app_secret
SCHWAB_REDIRECT_URI=http://localhost:8788/callback
COOKIE_ENCRYPTION_KEY=your_random_key_here
LOG_LEVEL=DEBUG  # Optional: Enable debug logging

在本地运行：

npm run dev
# Server will be available at http://localhost:8788

使用 MCP Inspector 连接到 http://localhost:8788/sse 进行测试。

架构

技术栈

• 运行时：Cloudflare Workers 和 Durable Objects
• 身份验证：通过 @cloudflare/workers-oauth-provider 实现 OAuth 2.0 和 PKCE
• API 客户端：使用 @sudowealth/schwab-api 以类型安全的方式访问 Schwab API
• MCP 框架：使用 @modelcontextprotocol/sdk 和 workers-mcp 适配器
• 状态管理：使用 KV 存储令牌，使用 Durable Objects 管理会话状态

安全功能

1. OAuth 2.0 和 PKCE：安全的身份验证流程，可防止授权 代码被截获
2. 增强的令牌管理：
   • 集中式 KV 令牌存储，并支持自动迁移
   • 自动刷新令牌（在过期前 5 分钟）
   • 令牌持久化 31 天，并设置 TTL
3. 账户信息脱敏：自动将敏感账户标识符 替换为显示名称
4. 状态安全：使用 HMAC-SHA256 签名确保状态参数的完整性
5. Cookie 加密：使用 AES-256 加密客户端批准状态
6. 机密信息脱敏：自动屏蔽日志中的敏感数据

开发

可用脚本

npm run dev          # Start development server on port 8788
npm run deploy       # Deploy to Cloudflare Workers
npm run typecheck    # Run TypeScript type checking
npm run lint         # Run ESLint with automatic fixes
npm run format       # Format code with Prettier
npm run validate     # Run typecheck and lint together

调试

服务端包含全面的日志记录，并支持配置日志级别：

• 开发环境：终端输出带颜色的日志
• 生产环境：Cloudflare 控制面板 → Workers → Logs
• 日志级别：DEBUG、INFO、WARN、ERROR（通过 LOG_LEVEL 环境变量设置）

启用调试日志，以查看详细的 OAuth 流程和 API 交互：

# For local development
echo "LOG_LEVEL=DEBUG" >> .dev.vars

# For production
npx wrangler secret put LOG_LEVEL --secret="DEBUG"

错误处理

服务器采用健壮的错误处理机制，并使用特定的错误类型：

• 身份验证错误（401）：提示重新进行身份验证
• 客户端错误（400）：参数无效、缺少数据
• 服务器错误（500）：API 故障、配置问题
• 网络错误（503）：自动重试并逐步延长间隔
• 所有错误都包含请求 ID，便于排查 Schwab API 问题

贡献

1. Fork 此仓库
2. 创建功能分支（git checkout -b feature/amazing-feature）
3. 提交更改（git commit -m 'Add amazing feature'）
4. 推送到该分支（git push origin feature/amazing-feature）
5. 发起 Pull Request

许可证

MIT

故障排除

常见问题

1. “未找到 KV 命名空间”错误

   • 确保已创建 KV 命名空间并更新 wrangler.jsonc
   • 运行 npx wrangler kv:namespace list 进行验证

2. 身份验证失败

   • 确认 Schwab 应用设置中的重定向 URI 与此处完全一致
   • 使用 npx wrangler secret list 检查所有密钥是否已正确设置
   • 启用调试日志，以查看详细的 OAuth 流程

3. “Durable Objects 不可用”错误

   • 确保使用付费版 Cloudflare Workers 计划
   • 免费版不支持 Durable Objects

4. 令牌刷新问题

   • 服务器会在令牌到期前 5 分钟自动刷新
   • 令牌会自动从 clientId 键迁移到 schwabUserId 键
   • 检查 KV 命名空间中存储的令牌： npx wrangler kv:key list --namespace-id=<your-id>

近期更新

• 增强令牌管理：集中式 KV 令牌存储可防止令牌不一致
• 提升安全性：HMAC-SHA256 状态验证和自动密钥脱敏
• 改进错误处理：结构化错误类型，并映射 Schwab API 错误
• 可配置日志记录：提供调试模式，便于排查 OAuth 和 API 问题

致谢

• 基于 Cloudflare Workers 构建
• 使用 Model Context Protocol
• 由 @sudowealth/schwab-api 提供支持