内容
# bcs-mcp
**你的BCS世界投资组合——与AI对话。**
MCP服务器，连接Claude（Claude Code，Claude Desktop等任意MCP客户端）至[BCS Trade API](https://trade-api.bcs.ru/)。查看投资组合、行情、买卖盘、K线图，分析持仓并计划再平衡——用中文普通话。
这不是交易机器人，也不是“信号”。所有决策由你做出——服务器仅提供安全的数据访问权限。
借鉴[t-invest-mcp](https://github.com/human-turn/t-invest-mcp)（类似的T-投资服务器）——相同的安全模型和文件下载方式。
## 为什么是安全的
- **默认只读。** 即使你不显式启用交易操作，也不会注册交易。仅需一个**只读令牌**。
- **交易需确认。** 如果你启用交易，每次下单前服务器会显示确认对话框——“购买N股X？”——没有明确的“确认”不会下单。
- **BCS无沙盒环境**——因此请谨慎启用交易模式：每个下单都是真实的。
- 令牌存储在环境变量中，从不进入代码、日志或服务器响应。
快速入门部分将令牌放入客户端配置——为了长期使用，请将令牌存储在系统keychain中，参考：[docs/secure-token.md](docs/secure-token.md)。
## 快速入门（5分钟）
需要Node.js ≥ 22和BCS经纪账户。
1. **令牌。** 登录[BCS世界投资](https://lk.bcs.ru/)的网页版 → “个人资料” → “账户管理” → 点击经纪账户 → “API令牌” → “生成令牌”，类型为**“仅读取”**。令牌仅显示一次；有效期90天。令牌绑定到一个特定的账户。
2. **连接到Claude Code** - 只需一条命令，无需安装（[`bcs-mcp`](https://www.npmjs.com/package/bcs-mcp)包将从npm自动获取）：
```bash
claude mcp add bcs \
-e BCS_REFRESH_TOKEN=<你的令牌> \
-- npx -y bcs-mcp
```
对于Claude Desktop，相同的配置块在Settings → Developer → Edit Config中添加。
此JSON配置也适用于其他MCP客户端（Cursor，VS Code，Windsurf等）- 仅需更改写入位置：
```json
{
"mcpServers": {
"bcs": {
"command": "npx",
"args": ["-y", "bcs-mcp"],
"env": { "BCS_REFRESH_TOKEN": "<你的令牌>" }
}
}
}
```
<details><summary>源码变体（用于开发）</summary>
```bash
git clone https://github.com/human-turn/bcs-mcp && cd bcs-mcp
npm install && npm run build
# 在上面的命令中，将"npx -y bcs-mcp"替换为"node /path/to/bcs-mcp/dist/index.js"
```
</details>
在此最小配置中，服务器**严格只读**：可以查看和分析所有内容，但不能交易（甚至不注册交易操作）。交易和文件下载可以通过`env`变量启用 - 参见[环境变量](#环境变量)，每个变量默认为禁用。
3. **检查：** 询问“显示我的BCS投资组合”。
## 现成可用：斜杠命令
在Claude Code中作为`/bcs:<名称>`出现：
| 命令 | 功能 |
|---|---|
| `portfolio_review` | 完整审查：结构、集中度、风险 |
| `rebalance_check` | 目标权重偏差 + 交易计划（以手为单位，无执行） |
| `invest_cash <金额>` | 工资来了：要买什么来接近目标 |
| `bond_picker <金额> <期限>` | 债券筛选：评级、息票、收益率、阶梯 |
| `fire_progress` | 进展到目标（FIRE）来自`portfolio-target.json`：预测、所需贡献 |
| `position_deep_dive <股票代码>` | 深入分析：卡片、动态、我的持仓 |
| `trades_review [天数]` | 我的交易：成交量、平均价格、佣金 |
| `weekly [金额]` | 每周例行：摘要 + 购买计划 |
| `quarterly` | 投资组合审查 + 再平衡检查 |
| `feedback [主题]` | 问题报告给开发者（无令牌和个人信息） |
所有命令**分析和建议** - 没有一个会自动交易。
再平衡的目标权重由项目根目录下的`portfolio-target.json`文件定义（示例MCP资源`bcs://portfolio-target/example`，格式与t-invest-mcp兼容）。
BCS Trade API不提供股息和利息 - 可以连接公共的[moex-mcp](https://github.com/cyberash-dev/moex-mcp)（MOEX ISS）：命令会考虑这一点。
## 环境变量
| 变量 | 值 | 描述 |
|---|---|---|
| `BCS_REFRESH_TOKEN` | 必需 | 来自BCS个人账户的刷新令牌（90天，有效期与账户绑定） |
| `BCS_ALLOW_TRADING` | `true`/`false` | 注册place/edit/cancel_order。需要“交易和读取”令牌。**真实资金！** |
| `BCS_CONFIRM` | `off` | 禁用交易确认提示（默认启用；不建议禁用 - 无沙盒环境） |
| `BCS_OUTPUT_DIR` | 路径 | 文件下载的根目录`outputPath`（默认为服务器的工作目录） |
## 工具
只读（始终）：
| 工具 | 描述 |
|---|---|
| `get_portfolio` | 投资组合：持仓与盈亏、权重、价值（RUB/USD/EUR）；按类别汇总（默认为T0） |
| `get_limits` | 资金和存款限额：按货币的可用资金（`free` = 数量 - 锁定；当日的快照） |
| `get_quotes` | 行情（批量）：买入/卖出、最新价、开盘/高/低、每日变化 |
| `get_order_book` | 买卖盘（深度20） |
| `get_recent_trades` | 无名交易记录：最新的`limit`（可扩展窗口），`from`/`to`时间段；通过`outputPath`完整记录到文件 |
| `get_candles` | K线图（OHLCV，M1...MN）；使用`outputPath`整个记录到文件 |
| `find_instrument` | 按股票代码/ISIN查找：手数、classCode、息票、股息收益率、评级（每只股票一张卡片；`allBoards`所有交易平台） |
| `get_instruments_by_type` | 按类型分类的工具目录（股票/债券/ETF/期货...），分页 |
| `get_trading_schedule` | 今日交易时段（按时区排序） |
| `get_trading_status` | 工具当前交易状态 + 与时间表的交叉检查（出现偏差时的`warning`） |
| `get_discounts` | 保证金折扣（多头/空头） |
| `get_orders` | 订单列表（2026-01-26后的数据） |
| `get_order_status` | 按UUID或交易编号查询订单状态 |
| `get_trades` | 我的已成交交易（2026-01-26后的数据） |
| `get_server_info` | 服务器诊断信息（用于反馈） |
交易（`BCS_ALLOW_TRADING=true`）：`place_order`、`edit_order`、`cancel_order`。
**重要：** 订单中的数量以手为单位（不是以股为单位 - `lotSize`来自`find_instrument`）。
### 文件下载
每个只读工具都接受`outputPath`（相对于`BCS_OUTPUT_DIR`的路径）和`outputFormat`（`json`/`csv`）。服务器将结果写入磁盘，并在对话框中返回摘要。对于`get_candles`和`get_instruments_by_type`，这包括通过分段下载完整的记录/目录。仅在下载根目录内允许写入。
## BCS Trade API限制
- 无资金交易历史（获得股息、佣金、充值）- 仅交易所交易。XIRR和税务报告因此无法实现。
- 无沙盒环境。
- 一个令牌 = 一个账户（多个账户 - 多个服务器实例）。
- 订单/交易列表 - 仅2026-01-26后。
## 免责声明
不构成个人投资建议。所有交易决策由您自行做出。`place_order`操作真实资金 - 请谨慎启用`BCS_ALLOW_TRADING=true`并保持交易确认开启。
## License
Apache 2.0
