t-invest-mcp

# t-invest-mcp **Your T-Investments portfolio in dialogue with AI.** MCP server that connects Claude (Claude Code, Claude Desktop — and any other MCP client) to [T-Invest API](https://developer.tbank.ru/invest/). Look at your portfolio, analyze securities, calculate payouts and rebalancing — with ordinary phrases, in Russian.  This is not a trading robot and not "signals". You always make decisions — the server only provides a safe access to your brokerage account data. ## Why it's safe - **Read-only by default.** Trading operations are not even registered until you explicitly enable them. A **read-only** token is sufficient. - **Transactions — only with your confirmation.** If you enable trading, the server shows a dialog "Buy N lots of X?" — without explicit "yes", the request will not be sent, regardless of the settings used by the agent. - **Sandbox.** Any idea can be tested on a virtual account with real quotes. - The token lives only in the environment variable — not in the code, not in the config, not in the logs. For production, keep it in the system keychain, not in the shell profile — the recipe is in [docs/secure-token.md](docs/secure-token.md). ## Quick start (5 minutes) Node.js ≥ 22 and a T-Investments account are required. 1. **Token.** In [T-Investments settings](https://www.tbank.ru/invest/settings/api/), issue a **read-only** token. "Confirmation of transactions with a code" should be disabled. The token is shown once; it lives for 3 months from the last use. 2. **Connection to Claude Code** — with one command, no installation required (the [`t-invest-mcp`](https://www.npmjs.com/package/t-invest-mcp) package will be pulled from npm): ```bash claude mcp add t-invest \ -e TINKOFF_API_TOKEN=<your-token> \ -- npx -y t-invest-mcp ``` For Claude Desktop, the same block is added in Settings → Developer → Edit Config. This JSON is suitable for any other MCP client (Cursor, VS Code, Windsurf, etc.) — only the place to write it changes: ```json { "mcpServers": { "t-invest": { "command": "npx", "args": ["-y", "t-invest-mcp"], "env": { "TINKOFF_API_TOKEN": "<your-token>" } } } } ``` <details><summary>Variant from sources (for development)</summary> ```bash git clone https://github.com/human-turn/t-invest-mcp && cd t-invest-mcp npm install && npm run build # then in the above commands, replace "npx -y t-invest-mcp" with "node /path/to/t-invest-mcp/dist/index.js" ``` </details> In this minimal configuration, the server is **strictly read-only**: you can look and analyze everything, but you cannot trade (trading operations are not even registered). Other features are enabled by environment variables — each is disabled by default: | Variable | What enables | |---|---| | `TINKOFF_SANDBOX=true` | [Sandbox](#trading-is-optional-disabled-by-default): a virtual account with real quotes — safe testing (requires a separate sandbox token) | | `TINKOFF_ALLOW_TRADING=true` | [Trading](#trading-is-optional-disabled-by-default): placing/canceling orders, each transaction — with your confirmation (requires a full-access token) | | `TINKOFF_OUTPUT_DIR=<path>` | Where to save [file downloads](#file-download---details) (default — project folder) | | `TINKOFF_CONFIRM=off` | Disable transaction confirmation dialog — only for sandbox | 3. **Verification:** ask "show me my accounts and portfolio". ## Ready-made rituals  Don't want to come up with requests? The server has ready-made recipes. In Claude Code, they appear as slash commands `/t-invest:<name>`: | Ritual | What it does | |---|---| | `weekly [amount]` | Weekly digest: what grew/fell and why, upcoming events; if you specify a replenishment amount — a plan for additional purchases | | `monthly` | Monthly results: honest profitability (XIRR with replenishments), payouts, commissions + payment calendar | | `quarterly` | Portfolio overview + check if it's time to rebalance | And separate commands for specific tasks: | Command | What it does | |---|---| | `portfolio_review` | Full review: structure, concentration, risks | | `payout_calendar` | Coupons and dividends for N months ahead, average monthly payout | | `bond_picker <amount> <horizon>` | Bond selection: yield with NCD, offer filter, ladder | | `rebalance_check` | Drift from target shares + transaction plan in lots (without execution) | | `invest_cash <amount>` | Salary came: where to buy to get closer to goals | | `position_deep_dive <ticker>` | Paper analysis: fundamentals, forecasts, payouts, dynamics | | `tax_helper [year]` | Taxes for the year + candidates for long-term ownership benefit | | `div_screener [min. %]` | Dividend stock screening MOEX | | `monthly_report`, `weekly_digest`, `fire_progress` | Parts of rituals — can be called separately | | `feedback [topic]` | Something doesn't work? Collects a report with diagnostics for developers (without token and personal data) | All commands **analyze and offer** — none of them make transactions on their own. ### Found an issue? `/t-invest:feedback` The command itself collects a report for developers: server diagnostics (`get_server_info` — version, modes, environment), reproduction steps, and exact error texts from the dialog. Before saving, **it will show you the text and ask if you want to mask account numbers and amounts** — the token never gets into the report. The result is saved in `feedback/FEEDBACK-<date>-<topic>.md`; further, at your discretion — a GitHub issue in one step or send the file yourself. ## Your strategy The main property of the server: it **does not impose methodology**. The commands above are a bonus, not a framework. Under the hood — 20+ tools (portfolio, operations, quotes, coupons, fundamentals, forecasts…), from which the model collects an answer to any your question: - **Just ask.** "What is my share of currency assets?", "compare my oil papers by P/E", "what will happen with coupons if I sell half of OFZ?" — without any commands. - **Describe your rules in text.** Put your strategy in `CLAUDE.md` of the project («no more than 10% per issuer», «dividends are reinvested in bonds», «new positions — only after reporting analysis») — and the agent will take it into account in each answer. - **Target shares — if needed.** The `portfolio-target.json` file in the project root enables rebalancing and a plan for additional purchases. Minimum — only class shares; `byTicker` and financial goals (`goals`) — optional enhancements. Example: MCP resource `t-invest://portfolio-target/example`. ```json { "targets": { "shares": 55, "bonds": 30, "etf": 10, "cash": 5 } } ``` - **Data — in your hands.** Each tool can download the result to a file (`outputPath`, CSV/JSON) — raw data does not eat up the dialog context, but gets to disk for pandas/Excel/anything. `get_operations` downloads the entire transaction history, `get_candles` — years of candles, and `download_history_archive` takes minutes for whole years (1 request = 1 year; available years will be shown by `get_history_archive_years`). Further — any your analytics: backtests, charts, reports. ## Trading (optional, disabled by default) If you want not only to analyze but also to execute — enable it explicitly: ```bash TINKOFF_ALLOW_TRADING=true # registers place_order / cancel_order ``` A full-access token is required. Three-layer protection: 1. **Confirmation in the server itself** (enabled by default): before a request — a dialog to the user through MCP elicitation; clients without elicitation support receive a refusal. Disabling — `TINKOFF_CONFIRM=off` (recommended only for sandbox). 2. **Ask-rules of Claude Code** (client layer, works even before calling): ```json { "permissions": { "allow": ["mcp__t-invest"], "ask": ["mcp__t-invest__place_order", "mcp__t-invest__cancel_order"] } } ``` Priority deny → ask → allow guarantees a prompt in any mode, including `bypassPermissions`. MCP tool annotations (`destructiveHint`) — just hints, Claude Code does not consider them. 3. **Sandbox for testing:** ```bash TINKOFF_API_TOKEN=<sandbox-token> TINKOFF_SANDBOX=true TINKOFF_ALLOW_TRADING=true ``` Accounts/portfolio/orders go to sandbox (virtual money, real quotes), `sandbox_*` tools appear. Ask the agent: "open a sandbox account, put a million and collect a model portfolio 60/40". ### Environment Variables | Variable | Value | Description | |---|---|---| | `TINKOFF_API_TOKEN` | required | T-Invest API token (read-only is sufficient for basic mode) | | `TINKOFF_SANDBOX` | `true`/`false` | Sandbox: accounts/portfolio/orders go to sandbox, `sandbox_*` tools are registered. Requires a sandbox token | | `TINKOFF_ALLOW_TRADING` | `true`/`false` | Registers `place_order`/`cancel_order`. In live mode — real money! | | `TINKOFF_CONFIRM` | `off` | Disables built-in elicitation confirmation of transactions (enabled by default) | | `TINKOFF_OUTPUT_DIR` | path | Root for file downloads `outputPath` (default is the server's cwd, i.e., project root) | ### Tools Read-only (always): | Tool | Description | |---|---| | `get_accounts` | List of brokerage accounts | | `get_portfolio` | Portfolio: amounts by asset classes, profitability, positions with tickers | | `get_operations` | Operations (transactions, dividends, coupons, commissions); with `outputPath` — entire history | | `find_instrument` | Search for an instrument by ticker/ISIN/FIGI/name | | `get_instrument` | Instrument card (lot, currency, exchange, assetUid; for bonds — nominal value, redemption, accrued interest) | | `get_last_prices` | Latest prices (batch), with a quote unit sign | | `get_candles` | OHLCV candles (1min…month); with `outputPath` — entire period in chunks | | `get_order_book` | Order book | | `get_dividends` | Dividends: history and announcements | | `get_bond_coupons` | Bond coupon calendar | | `get_accrued_interests` | Bond accrued interest | | `get_bond_events` | Bond events: coupons, offers, redemption | | `get_asset_fundamentals` | Fundamentals: P/E, EV/EBITDA, ROE, debt, dividend yield, etc. | | `get_forecasts` | Analyst consensus forecasts and targets | | `get_trading_schedules` | Trading schedules for the week | | `get_active_orders` | Active orders | | `download_history_archive` | Annual archives of minute candles (1 request = 1 year) → single CSV | | `get_history_archive_years` | Available archive years for an instrument (and their size) | | `download_trades_archive` | Anonymous trades for a trading day → CSV | | `get_server_info` | Server diagnostics: version, modes, environment (for feedback) | Trading (`TINKOFF_ALLOW_TRADING=true`): `place_order`, `cancel_order`. Sandbox (`TINKOFF_SANDBOX=true`): `sandbox_open_account`, `sandbox_pay_in`, `sandbox_close_account`. ### File Download — details Each read-tool accepts `outputPath` (path relative to `TINKOFF_OUTPUT_DIR`) and `outputFormat` (`json`/`csv`). The server writes the result to disk, returns a summary (`savedTo`, `records`, `bytes`, `sample`) in the dialog. Recording is possible only within the download root; progress of long downloads is visible in the client. ### portfolio-target.json — full format ```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` classes sum up to 100; money market funds (LQDT, etc.) can be classified as `cash`. `goals` is an array, and there can be multiple goals; only needed for progress commands (`fire_progress`, `monthly` ritual). Built on the official SDK [`@tinkoff/invest-js`](https://opensource.tbank.ru/invest/invest-js) (gRPC). ## Disclaimer Not an individual investment recommendation. You make all trading decisions yourself. In live mode, `place_order` operates with real money — use `TINKOFF_ALLOW_TRADING=true` consciously and keep transaction confirmation enabled. ## License Apache 2.0