Content
# bcs-mcp
**Your BCS World of Investments portfolio — in dialogue with AI.**
MCP server connecting Claude (Claude Code, Claude Desktop — and any other MCP client) to [BCS Trade API](https://trade-api.bcs.ru/). View your portfolio, quotes, order book, candles, analyze positions, and plan rebalancing — with ordinary phrases, in Russian.
This is not a trading robot or "signals". You always make decisions — the server only provides a safe model access to your brokerage account data.
Built on the model of [t-invest-mcp](https://github.com/human-turn/t-invest-mcp) (a similar server for T-Investments) — the same security model and file downloads.
## 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 "Buy N pcs. X?" dialog before each order — without an explicit "yes" the order won't go through.
- **No sandbox at BCS** — so enable trading mode consciously: each order is real.
- The token lives in an environment variable and never gets into code, logs, or server responses. The quick start below puts it into the client config — for permanent use, keep the token in a system keychain, recipe: [docs/secure-token.md](docs/secure-token.md).
## Quick Start (5 minutes)
Requires Node.js ≥ 22 and a brokerage account at BCS.
1. **Token.** Log in to the web version of [BCS World of Investments](https://lk.bcs.ru/) → "Profile" → "Account management" → click on the brokerage account → "API tokens" → "Issue token", type **"Read-only"**. The token is shown once; lives for 90 days. The token is tied to exactly one account.
2. **Connection to Claude Code** — with one command, no installation required (package [`bcs-mcp`](https://www.npmjs.com/package/bcs-mcp) will be pulled from npm):
```bash
claude mcp add bcs \
-e BCS_REFRESH_TOKEN=<your-token> \
-- npx -y bcs-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.) — just change the place to write it:
```json
{
"mcpServers": {
"bcs": {
"command": "npx",
"args": ["-y", "bcs-mcp"],
"env": { "BCS_REFRESH_TOKEN": "<your-token>" }
}
}
}
```
<details><summary>Variant from sources (for development)</summary>
```bash
git clone https://github.com/human-turn/bcs-mcp && cd bcs-mcp
npm install && npm run build
# then in the above commands replace "npx -y bcs-mcp" → "node /path/to/bcs-mcp/dist/index.js"
```
</details>
In this minimal configuration, the server is **strictly read-only**: you can view and analyze everything, but you can't trade (trading operations are not even registered). Trading and file downloads are enabled by environment variables — see [Environment Variables](#environment-variables), each disabled by default.
3. **Verification:** ask "show my BCS portfolio".
## Ready-to-use: slash commands
In Claude Code, they appear as `/bcs:<name>`:
| Command | What it does |
|---|---|
| `portfolio_review` | Full review: structure, concentration, risks |
| `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 |
| `bond_picker <amount> <horizon>` | Screening bond catalog: rating, coupon, yield, ladder |
| `fire_progress` | Progress to goals (FIRE) from `portfolio-target.json`: forecast, required contribution |
| `position_deep_dive <ticker>` | Paper analysis: card, dynamics, my position |
| `trades_review [days]` | My trades for the period: turnover, average prices, commissions |
| `weekly [amount]` | Weekly ritual: digest + purchase plan |
| `quarterly` | Portfolio review + rebalancing check |
| `feedback [topic]` | Report on a problem for developers (without token and personal data) |
All commands **analyze and offer** — none of them make trades themselves. Target shares for rebalancing are set by the `portfolio-target.json` file in the project root (the standard is MCP resource `bcs://portfolio-target/example`, format compatible with t-invest-mcp).
Dividends and coupons BCS Trade API does not return — you can connect a public [moex-mcp](https://github.com/cyberash-dev/moex-mcp) (MOEX ISS) nearby: commands take this into account.
## Environment Variables
| Variable | Value | Description |
|---|---|---|
| `BCS_REFRESH_TOKEN` | required | Refresh token from BCS personal account (90 days, tied to account) |
| `BCS_ALLOW_TRADING` | `true`/`false` | Registers place/edit/cancel_order. Requires a "for trading and reading" token. REAL money! |
| `BCS_CONFIRM` | `off` | Disables elicitation confirmation of transactions (enabled by default; not recommended to disable — no sandbox) |
| `BCS_OUTPUT_DIR` | path | Root for file downloads `outputPath` (by default — server cwd) |
## Tools
Read-only (always):
| Tool | Description |
|---|---|
| `get_portfolio` | Portfolio: positions with P&L, shares, cost in RUB/USD/EUR; results by classes (slice `term`, default T0) |
| `get_limits` | Cash and deposit limits: free funds by currencies (`free` = quantity − locked; snapshot at the beginning of the day) |
| `get_quotes` | Quotes (batch): bid/offer, last, open/high/low, change per day |
| `get_order_book` | Order book L2 (depth 20) |
| `get_recent_trades` | Tape of anonymous trades: newest `limit` (expandable window), period `from`/`to`; full period to file — via `outputPath` |
| `get_candles` | OHLCV candles (M1…MN); with `outputPath` — entire period in chunks |
| `find_instrument` | Cards by tickers/ISIN: lot, classCode, coupons, dividend yield, ratings (one card per paper; `allBoards` — all platforms) |
| `get_instruments_by_type` | Catalog of instruments by type (stocks/bonds/ETFs/futures…), pagination |
| `get_trading_schedule` | Instrument sessions for today (MSK, sorted) |
| `get_trading_status` | Open/closed instrument now + cross-check with schedule (`warning` in case of discrepancy) |
| `get_discounts` | Margin discounts (long/short) |
| `get_orders` | List of orders (data from 26.01.2026) |
| `get_order_status` | Order status by UUID or exchange number |
| `get_trades` | My executed trades (data from 26.01.2026) |
| `get_server_info` | Server diagnostics (for feedback) |
Trading (`BCS_ALLOW_TRADING=true`): `place_order`, `edit_order`, `cancel_order`.
**Important:** quantity in orders — in pieces, not in lots (lot — `lotSize` from `find_instrument`).
### File Download
Each read-tool accepts `outputPath` (path relative to `BCS_OUTPUT_DIR`) and `outputFormat` (`json`/`csv`). The server writes the result to disk, returns a summary in the dialog. For `get_candles` and `get_instruments_by_type`, this includes downloading the entire period/catalog in chunks. Recording is possible strictly within the root of downloads.
## BCS Trade API Limitations
- No history of cash transactions (received dividends, commissions, replenishments) — only exchange trades. XIRR and tax reports are therefore impossible.
- No sandbox.
- One token = one account (multiple accounts — multiple server instances).
- Lists of orders/trades — only from 26.01.2026.
## Disclaimer
Not an individual investment recommendation. You make all trading decisions yourself. `place_order` operates with real money — use `BCS_ALLOW_TRADING=true` consciously and keep transaction confirmation enabled.
## License
Apache 2.0
