Schwab MCP

🚀 嘉信理财MCP服务器

嘉信理财MCP服务器是一个模型上下文协议（MCP）服务器，它使Claude等AI助手能够通过嘉信理财官方API，安全地与嘉信理财账户和市场数据进行交互。

🚀 快速开始

前提条件

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

快速设置

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

# 首次使用时，使用Cloudflare进行身份验证
npx wrangler login

# 创建用于存储OAuth令牌的KV命名空间
npx wrangler kv:namespace create "OAUTH_KV"
# 记录输出中的ID，配置时需要用到

# 设置个人配置
cp wrangler.example.jsonc wrangler.jsonc
# 编辑wrangler.jsonc：
# 1. 将YOUR_KV_NAMESPACE_ID_HERE替换为上面的ID
# 2. 将名称更改为唯一的名称（例如，"schwab-mcp-yourname"）

# 设置密钥
npx wrangler secret put SCHWAB_CLIENT_ID      # 您的嘉信理财应用密钥
npx wrangler secret put SCHWAB_CLIENT_SECRET  # 您的嘉信理财应用密钥
npx wrangler secret put SCHWAB_REDIRECT_URI   # https://your-worker-name.workers.dev/callback
npx wrangler secret put COOKIE_ENCRYPTION_KEY # 使用openssl rand -hex 32生成

# 部署
npm run deploy

配置说明

• wrangler.example.jsonc - 模板配置（已提交）
• wrangler.jsonc - 您的个人配置（git忽略，从模板创建）
• .dev.vars - 本地开发密钥（git忽略，可选）

由于wrangler.jsonc被git忽略，您可以安全地使用个人配置进行开发和测试，而不会泄露密钥。

详细配置

1. 创建嘉信理财应用

1. 登录 嘉信理财开发者门户。
2. 创建一个新应用，设置如下：
   • 应用名称：您的MCP服务器名称。
   • 回调URL：https://schwab-mcp.<your-subdomain>.workers.dev/callback。
   • 应用类型：根据您的用例选择个人或第三方。
3. 记录您的 应用密钥（客户端ID）并生成一个 应用密钥。

2. 设置环境变量

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

GitHub Actions部署

对于自动部署，添加以下GitHub仓库密钥：

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

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

使用Inspector进行测试

使用MCP Inspector测试您的部署：

npx @modelcontextprotocol/inspector@latest

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

✨ 主要特性

交易工具

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

市场数据工具

• 工具搜索
  • searchInstruments：按符号搜索证券，并提供基本面/参考数据。
• 价格历史
  • getPriceHistory：获取可自定义周期和频率的历史价格数据。
• 市场时间
  • getMarketHours：按日期检查市场营业时间。
  • getMarketHoursByMarketId：获取特定市场信息。
• 市场动态
  • getMovers：按指数（$SPX、$COMPX、$DJI）查找顶级市场动态。
• 期权链
  • getOptionChain：检索包含希腊字母的完整期权链数据。
  • getOptionExpirationChain：获取期权到期日期。

📦 安装指南

前提条件

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

快速设置

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

# 首次使用时，使用Cloudflare进行身份验证
npx wrangler login

# 创建用于存储OAuth令牌的KV命名空间
npx wrangler kv:namespace create "OAUTH_KV"
# 记录输出中的ID，配置时需要用到

# 设置个人配置
cp wrangler.example.jsonc wrangler.jsonc
# 编辑wrangler.jsonc：
# 1. 将YOUR_KV_NAMESPACE_ID_HERE替换为上面的ID
# 2. 将名称更改为唯一的名称（例如，"schwab-mcp-yourname"）

# 设置密钥
npx wrangler secret put SCHWAB_CLIENT_ID      # 您的嘉信理财应用密钥
npx wrangler secret put SCHWAB_CLIENT_SECRET  # 您的嘉信理财应用密钥
npx wrangler secret put SCHWAB_REDIRECT_URI   # https://your-worker-name.workers.dev/callback
npx wrangler secret put COOKIE_ENCRYPTION_KEY # 使用openssl rand -hex 32生成

# 部署
npm run deploy

💻 使用示例

基础用法

# 本地开发
npm run dev
# 服务器将在http://localhost:8788可用

高级用法

# 部署到Cloudflare Workers
npm run deploy

Claude桌面配置

1. 使用Claude集成

1. 转到 Claude桌面 设置。
2. 点击“集成”选项卡。
3. 点击“添加自定义集成”按钮。
4. 输入集成名称“Schwab”。
5. 输入MCP服务器URL：https://schwab-mcp.<your-subdomain>.workers.dev/sse。
6. 点击“添加”按钮。
7. 点击“连接”，嘉信理财身份验证流程将启动。

2. 将MCP服务器添加到Claude桌面配置

将以下内容添加到您的Claude桌面配置文件中：

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

重启Claude桌面。首次使用嘉信理财工具时，将打开一个浏览器窗口进行身份验证。

示例命令

连接后，您可以要求Claude：

• “显示我的嘉信理财账户余额”
• “获取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  # 可选：启用调试日志

在本地运行：

npm run dev
# 服务器将在http://localhost:8788可用

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

📚 详细文档

架构

技术栈

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

安全特性

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

开发

可用脚本

npm run dev          # 在端口8788上启动开发服务器
npm run deploy       # 部署到Cloudflare Workers
npm run typecheck    # 运行TypeScript类型检查
npm run lint         # 运行ESLint并自动修复
npm run format       # 使用Prettier格式化代码
npm run validate     # 同时运行类型检查和代码检查

调试

服务器包含可配置级别的全面日志记录：

• 开发环境：终端输出，带有彩色日志。
• 生产环境：Cloudflare仪表板 → Workers → 日志。
• 日志级别：DEBUG、INFO、WARN、ERROR（通过LOG_LEVEL环境变量设置）。

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

# 本地开发
echo "LOG_LEVEL=DEBUG" >> .dev.vars

# 生产环境
npx wrangler secret put LOG_LEVEL --secret="DEBUG"

错误处理

服务器实现了强大的错误处理，具有特定的错误类型：

• 身份验证错误（401）：提示重新进行身份验证。
• 客户端错误（400）：参数无效、数据缺失。
• 服务器错误（500）：API失败、配置问题。
• 网络错误（503）：自动重试，带有退避策略。 所有错误都包含请求ID，用于嘉信理财API故障排除。

贡献

1. 分叉仓库。
2. 创建功能分支（git checkout -b feature/amazing-feature）。
3. 提交更改（git commit -m 'Add amazing feature'）。
4. 推送到分支（git push origin feature/amazing-feature）。
5. 打开拉取请求。

故障排除

常见问题

1. “KV命名空间未找到”错误
   • 确保您创建了KV命名空间并更新了wrangler.jsonc。
   • 运行npx wrangler kv:namespace list进行验证。
2. 身份验证失败
   • 验证您的重定向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状态验证和自动密钥编辑。
• 更好的错误处理：结构化错误类型，带有嘉信理财API错误映射。
• 可配置的日志记录：调试模式，用于解决OAuth和API问题。

致谢

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

📄 许可证

本项目采用MIT许可证。

⚠️ 重要提示

这是一个非官方的、由社区开发的嘉信理财TypeScript MCP服务器。它未经嘉信理财批准、认可或认证。按原样提供，其功能可能不完整或不稳定。使用时请自行承担风险，尤其是在处理财务数据或交易时。