内容
# t-invest-mcp
**您的T-Инвестиции投资组合，以对话方式与AI互动.**
MCP服务器，连接Claude（Claude Code，Claude Desktop等任意MCP客户端）至[T-Invest API](https://developer.tbank.ru/invest/)。您可以查看投资组合，分析证券，计算分红和再平衡 - 只需使用简单的中文语句。
这不是一个交易机器人，也不是“信号”。所有决策仍由您自行做出 - 服务器仅提供一种安全的方式访问您的券商账户数据。
## 为什么这是安全的
- **默认只读**。除非您明确启用，否则不会记录交易操作。仅需一个**只读**令牌。
- **交易需要您的确认**。如果您启用交易，每次委托前，服务器都会显示一个对话框，询问“是否购买N手X？”，如果没有明确的“确认”，委托将不会执行。
- **沙盒环境**。任何想法都可以在虚拟账户中进行测试，使用实时行情。
- 令牌仅存储在环境变量中 - 不存储在代码中，不存储在配置文件中，不存储在日志中。对于生产环境，请将其存储在系统密钥链中，而不是shell配置文件中 - 参考[docs/secure-token.md](docs/secure-token.md)。
## 快速开始（5分钟）
需要Node.js ≥ 22和T-Инвестиции账户。
1. **令牌**。在[T-Инвестиции设置](https://www.tbank.ru/invest/settings/api/)中颁发一个“只读”令牌。必须关闭“交易确认码”。
令牌仅显示一次；自上次使用以来有效期为3个月。
2. **连接到Claude Code** - 只需一条命令，无需安装（`t-invest-mcp`包将从npm下载）：
```bash
claude mcp add t-invest \
-e TINKOFF_API_TOKEN=<您的令牌> \
-- npx -y t-invest-mcp
```
对于Claude Desktop，相同的块添加到Settings → Developer → Edit Config。
此JSON适用于任何其他MCP客户端（Cursor，VS Code，Windsurf等）- 唯一需要更改的是写入位置：
```json
{
"mcpServers": {
"t-invest": {
"command": "npx",
"args": ["-y", "t-invest-mcp"],
"env": { "TINKOFF_API_TOKEN": "<您的令牌>" }
}
}
}
```
<details><summary>从源代码编译（适用于开发）</summary>
```bash
git clone https://github.com/human-turn/t-invest-mcp && cd t-invest-mcp
npm install && npm run build
# 在上面的命令中，将"npx -y t-invest-mcp"替换为"node /path/to/t-invest-mcp/dist/index.js"
```
</details>
在此最小配置中，服务器**严格只读**：您可以查看和分析所有内容，但不能交易（甚至不会记录交易操作）。其他功能通过环境变量启用，每个功能默认关闭：
| 变量 | 功能 |
|---|---|
| `TINKOFF_SANDBOX=true` | [沙盒环境](#交易可选默认关闭): 虚拟账户实时行情 - 安全测试（需要单独的sandbox令牌） |
| `TINKOFF_ALLOW_TRADING=true` | [交易](#交易可选默认关闭): 委托/撤销委托，每笔交易需您确认（需要full-access令牌） |
| `TINKOFF_OUTPUT_DIR=<路径>` | 存储[文件导出](#导出到文件-详情)的位置（默认为服务器项目目录） |
| `TINKOFF_CONFIRM=off` | 关闭交易确认对话框 - 仅适用于沙盒环境 |
3. **检查**：询问“显示我的账户和投资组合”。
## 成品：仪式
如果您不想思考查询语句 - 服务器中已包含预设模板。在Claude Code中，它们作为斜杠命令`/t-invest:<名称>`出现:
| 仪式 | 功能 |
|---|---|
| `weekly [金额]` | 周总结：什么上涨/下跌以及原因，未来事件；如果指定充值金额 - 则为追加计划 |
| `monthly` | 月总结：实际收益率（考虑充值），分红，手续费 + 支付日历 |
| `quarterly` | 投资组合概览 + 是否需要再平衡检查 |
以及用于特定任务的单独命令：
| 命令 | 功能 |
|---|---|
| `portfolio_review` | 完整概览：结构，集中度，风险 |
| `payout_calendar` | 未来N个月的息票和股息，月平均支付 |
| `bond_picker <金额> <期限>` | 债券选择：收益率与NKD，报价筛选，阶梯 |
| `rebalance_check` | 目标权重偏差 + 交易计划（不执行） |
| `invest_cash <金额>` | 薪水来了：如何补充以接近目标 |
| `position_deep_dive <股票代码>` | 证券分析：基本面，预测，分红，动态 |
| `tax_helper [年]` | 年度税收 + 长期持有免税候选 |
| `div_screener [最小%]` | MOEX股息股票筛选 |
| `monthly_report`, `weekly_digest`, `fire_progress` | 仪式的组成部分 - 可单独调用 |
| `feedback [主题]` | 有问题？收集开发者报告（无令牌和个人信息） |
所有命令**分析和建议** - 没有一个命令会自行执行交易。
### 发现问题？`/t-invest:feedback`
该命令会自动为开发者收集报告：服务器诊断信息（版本，模式，环境），重现步骤和准确的错误文本。在保存之前**显示文本并询问是否屏蔽帐户号码和金额** - 令牌永远不会进入报告。结果存储在`feedback/FEEDBACK-<日期>-<主题>.md`中；接下来，您可以创建GitHub问题或自行发送文件。
## 自定义策略
服务器的主要特性：它**不强加方法论**。上面的命令是奖励，而不是框架。在底层 - 20多个工具构件（投资组合，操作，行情，息票，基本面，预测...），模型从中收集对任何问题的答案：
- **直接提问**。 “我的货币资产比例是多少？”，“比较我的石油股票的P/E”，“如果我卖出一半的OFZ，息票将如何变化？” - 无需任何命令。
- **用文本描述您的规则**。 将您的策略放入项目的`CLAUDE.md`中（“不允许单个发行人超过10%”，“股息再投资于债券”，“新头寸 - 仅在报告分析后”）- 代理将在每个答案中考虑它。
- **如果需要目标权重**。 `portfolio-target.json`文件位于项目根目录中，启用再平衡和追加计划。最小 - 仅类别权重；`byTicker`和财务目标（`goals`）是可选的高级功能。
模板：MCP资源`t-invest://portfolio-target/example`。
```json
{ "targets": { "shares": 55, "bonds": 30, "etf": 10, "cash": 5 } }
```
- **数据属于您**。 每个工具都可以将结果导出到文件（`outputPath`，CSV/JSON）- 原始数据不会占用对话上下文，而是存储在磁盘上以供pandas/Excel使用。 `get_operations`同时下载整个操作历史记录，`get_candles` - 数年的蜡烛图，而`download_history_archive` - 整年分钟图（1个请求=1年；可用年份将显示`get_history_archive_years`）。接下来 - 您自己的任何分析：回测，图表，报告。
## 交易（可选，默认关闭）
如果您不仅要分析还要执行 - 请明确启用：
```bash
TINKOFF_ALLOW_TRADING=true # 注册place_order / cancel_order
```
需要full-access令牌。 三层保护：
1. **服务器确认**（默认启用）：在委托之前 - 通过MCP询问用户；不支持询问的客户端会收到拒绝。禁用 - `TINKOFF_CONFIRM=off`（仅建议在沙盒环境中使用）。
2. **Claude Code的Ask规则**（客户端层，在调用前触发）：
```json
{
"permissions": {
"allow": ["mcp__t-invest"],
"ask": ["mcp__t-invest__place_order", "mcp__t-invest__cancel_order"]
}
}
```
优先级为deny → ask → allow，在任何模式下（包括`bypassPermissions`）保证提示。 MCP工具注释（`destructiveHint`）- 仅提示，Claude Code不考虑。
3. **沙盒环境用于测试：**
```bash
TINKOFF_API_TOKEN=<sandbox令牌> TINKOFF_SANDBOX=true TINKOFF_ALLOW_TRADING=true
```
账户/投资组合/委托进入沙盒环境（虚拟资金，实时行情），出现`sandbox_*`工具。 询问代理：“打开sandbox账户，投入一百万元并收集模型投资组合60/40”。
## 参考
### 环境变量
| 变量 | 值 | 描述 |
|---|---|---|
| `TINKOFF_API_TOKEN` | 必需 | T-Invest API令牌（足够基本的只读模式） |
| `TINKOFF_SANDBOX` | `true`/`false` | 沙盒环境：账户/投资组合/委托进入sandbox，注册`sandbox_*`工具。需要sandbox令牌 |
| `TINKOFF_ALLOW_TRADING` | `true`/`false` | 注册`place_order`/`cancel_order`。生产环境 - 真实资金！ |
| `TINKOFF_CONFIRM` | `off` | 关闭内置询问确认交易（默认启用） |
| `TINKOFF_OUTPUT_DIR` | 路径 | 文件导出的根目录`outputPath`（默认为服务器工作目录，即项目根目录） |
### 工具
只读（始终）：
| 工具 | 描述 |
|---|---|
| `get_accounts` | 券商账户列表 |
| `get_portfolio` | 投资组合：资产类别金额，收益率，持仓与股票代码 |
| `get_operations` | 操作（交易，股息，息票，手续费）；使用`outputPath` - 整个历史记录 |
| `find_instrument` | 按股票代码/ISIN/FIGI/名称搜索工具 |
| `get_instrument` | 工具卡片（手数，货币，交易所，assetUid；对于债券 - 面值，偿还日期，NKD） |
| `get_last_prices` | 最新价格（批处理），与报价单位标识 |
| `get_candles` | OHLCV蜡烛图（1min...month）；使用`outputPath` - 整个期间分段 |
| `get_order_book` | 委托簿 |
| `get_dividends` | 股息：历史和预测 |
| `get_bond_coupons` | 债券息票日历 |
| `get_accrued_interests` | 债券NKD |
| `get_bond_events` | 债券事件：息票，报价，偿还 |
| `get_asset_fundamentals` | 基本面：P/E，EV/EBITDA，ROE，债务，股息收益率等 |
| `get_forecasts` | 分析师共识预测和目标 |
| `get_trading_schedules` | 每周交易时间表 |
| `get_active_orders` | 活跃委托 |
| `download_history_archive` | 年度分钟蜡烛图存档（1个请求=1年）→ 单个CSV |
| `get_history_archive_years` | 工具可用存档年份（及其大小） |
| `download_trades_archive` | 交易日内匿名交易 → CSV |
| `get_server_info` | 服务器诊断：版本，模式，环境（用于反馈） |
交易（`TINKOFF_ALLOW_TRADING=true`）：`place_order`，`cancel_order`。
沙盒环境（`TINKOFF_SANDBOX=true`）：`sandbox_open_account`，`sandbox_pay_in`，`sandbox_close_account`.
### 文件导出 - 详情
每个只读工具接受`outputPath`（相对于`TINKOFF_OUTPUT_DIR`的路径）和`outputFormat`（`json`/`csv`）。 服务器将结果写入磁盘，并在对话框中返回摘要（`savedTo`，`records`，`bytes`，`sample`）。 仅在导出根目录内写入； 导出进度在客户端可见。
### portfolio-target.json - 完整格式
```json
{
"targets": { "shares": 55, "bonds": 30, "etf": 10, "cash": 5 },
"byTicker": { "SBER": 10 },
"goals": [
{ "name": "FIRE", "targetAmount": 30000000, "targetDate": "2035-01-01",
"monthlyContribution": 100000, "expectedAnnualReturnPct": 8 }
]
}
```
`targets`类别合计为100；货币市场基金（如LQDT等）可归为`cash`。 `goals` - 数组，可以有多个目标；仅需用于进度命令（`fire_progress`，仪式`monthly`）。
基于官方SDK [`@tinkoff/invest-js`](https://opensource.tbank.ru/invest/invest-js)（gRPC）构建。
## 免责声明
不构成个人投资建议。 所有交易决策均由您自行做出。 在生产环境中，`place_order`使用真实资金 - 请谨慎使用`TINKOFF_ALLOW_TRADING=true`并保持交易确认启用。
## License
Apache 2.0
