stockbit-mcp

# Stockbit MCP

**Bring Claude to your IDX trading desk.**

Accepting donations: [Saweria Link](https://saweria.co/GUBS)

Bandarmology, quotes, orderbook, fundamentals, your watchlists and portfolio — and, only if you
switch it on, confirm-gated order entry — through your own Stockbit account, from Claude Desktop,
Claude Code, Cursor or any MCP client.

[![npm](https://img.shields.io/npm/v/stockbit-mcp?color=cb3837&logo=npm)](https://www.npmjs.com/package/stockbit-mcp)
[![CI](https://github.com/INo-xious/stockbit-mcp/actions/workflows/ci.yml/badge.svg)](https://github.com/INo-xious/stockbit-mcp/actions/workflows/ci.yml)
[![Node](https://img.shields.io/badge/node-%E2%89%A522-5FA04E?logo=node.js&logoColor=white)](https://nodejs.org)
[![License](https://img.shields.io/badge/license-MIT-blue)](LICENSE)

English | [Bahasa Indonesia](README.id.md)

> [!WARNING]
> **Unofficial and unaffiliated.** This project is not affiliated with, endorsed by or supported by
> Stockbit, PT Stockbit Sekuritas Digital or the Indonesia Stock Exchange. Nothing it produces is
> investment advice, and the author is not a licensed adviser.

> [!IMPORTANT]
> **What you need.** A Stockbit account you log into yourself with a username and password — Google
> and Facebook sign-in are broken on Stockbit's own site. Node.js 22 or newer. A Chromium-family
> browser (Chrome, Edge, Brave, Vivaldi) for the one-time login. `broker_distribution` additionally
> needs a Rp 10,000,000 balance, which is Stockbit's gate, not this project's.

> [!NOTE]
> **Your data stays with you.** This runs on your machine, talks only to Stockbit's own API hosts
> with your own session, and keeps the refresh token in the macOS Keychain (an encrypted file
> elsewhere). Nothing is sent to the author. The only channels that leave your machine are the alert
> webhook and Telegram bot you configure yourself.

> [!CAUTION]
> **Undocumented API; trading off by default.** This uses the private JSON API behind Stockbit's own
> apps, which can change without notice. Automated access may conflict with Stockbit's Terms of Use
> — use it at your own risk, on your own account. Nothing here can place an order until you run
> `stockbit-auth trading-enable` yourself, at a terminal.

![Broker-to-broker flow for one stock over a month](docs/images/broker-distribution-sample.svg)

<sub>Broker-to-broker flow, rendered by the server. Synthetic data.</sub>

---

## How it works (and why it is safe to run)

It is an **HTTP client, not a bot.** Every number it reports comes from a JSON endpoint in a closed
route table — no headless browser scraping pages, no reading data off Stockbit's UI, no polling loop
you did not start.

- **One interactive login, captured from your own browser.** You sign in on Stockbit's real page;
  the server reads the refresh token out of the response and stores it. Your password never touches
  this code.
- **Three token domains, three separate stores.** `exodus` (market data), `carina` (Stockbit
  Sekuritas), `api-sekuritas` (e-IPO). Logging out of one leaves the others alone, and the route
  table decides which credential each request may carry.
- **The 24-hour access token is cached on disk, encrypted, and shared between processes.** Because
  the refresh token rotates on every use, N clients each minting their own access token retire each
  other's credential. Same AES-256-GCM and mode `0600` as the file-backend refresh token — which on
  macOS is a genuine reduction, since there the refresh token is in the Keychain and this is not.
  `STOCKBIT_NO_ACCESS_CACHE=1` turns it off. See [SECURITY.md](SECURITY.md).
- **A closed route table.** 153 permitted request shapes across three hosts, enumerated in
  `src/http/routes/`. Anything not in that table cannot be requested — `test/transport.test.ts`
  asserts it, and every one of the 32 non-GET routes is admitted by a named decision record.
- **Every log and every tool result is redacted.** Tokens, PINs and bot tokens are matched by shape
  as well as by key name.
- **A rate limit that behaves like a person.** Three concurrent requests, 150 ms apart.
- **Trading is a ladder you climb deliberately**: `off` → `stockbit-auth trading-enable --paper` →
  `--live`. The environment can only move you *down* it. Orders are two steps with a human in the
  middle, and where your client supports elicitation you are asked directly as well.

```mermaid
flowchart LR
  C["Claude Desktop / Code / Cursor"] <-->|MCP over stdio| S["stockbit-mcp<br/>(your machine)"]
  S -->|market data| E["exodus.stockbit.com"]
  S -->|portfolio, orders| K["carina.stockbit.com"]
  S -->|IPO| A["api-sekuritas.stockbit.com"]
  S -.->|drawing only| B["your logged-in browser"]
  S -.->|paper mode| L["local ledger"]
```

## What this tool does not do

- **No PIN handling by any tool.** The six-digit trading PIN is typed at your terminal, used for one
  request and never stored. If anything asks you for it through an assistant, that is not this.
- **No order without a ticket.** By default, the write tools also need your confirmation. The only
  exception is capped `--auto-confirm`, which you must deliberately enable for live trading at a
  terminal; a model cannot enable it or widen its value cap. The tools take no price or quantity, so
  what reaches the exchange is exactly what the ticket described.
- **No auto-resend, no auto-cancel.** When an order's outcome is uncertain the server says so and
  stops. A resend is how one intention becomes two orders.
- **Saved workflow recipes cannot write.** Enforced by construction: a write tool is never added to
  the map recipes look names up in.
- **No route outside the table.** No day-trade or smart orders, no withdrawals, no deposits, no
  posting to the stream.
- **No scraping, and no UI automation for data.** Your own browser is used for three things and
  nothing else: the one-time login, drawing on your own chart, and opening Stockbit when you ask to
  look at it. Nothing is ever read out of the page.
- **Nothing leaves your machine** except to Stockbit, and to channels you configured.
- **No short selling** — IDX retail has none — and **no financial advice**.

## Prerequisites

| | |
|---|---|
| **Stockbit account** | Username and password. Google/Facebook sign-in is broken upstream. |
| **Node.js** | 22 or newer. (`src/auth/cdp.ts` needs a global `WebSocket`.) |
| **A browser** | Chromium-family for the one-time login. Or import a HAR from any browser. |
| **macOS** | The Keychain prompts once when the token is stored. |
| **Windows** | Run the login in a terminal, or use the `login` tool from your client. |
| **Linux** | `notify-send` for desktop alerts; the encrypted file store is used instead of a keychain. |
| **Rp 10,000,000** | Only for `broker_distribution`. Stockbit's gate. Everything else works without it. |

## What it does

**Bandarmology.** `broker_summary`, `broker_distribution`, `broker_activity`, `bandar_detector` —
who accumulated, who distributed, and who was on the other side of the tape. NET and GROSS, all four
market boards, ten period windows including year-to-date in a single request. This is the data no
other market API has, and it is why this project exists.

**Market, company and fundamentals.** Quotes, full orderbook depth, auto-rejection bands, movers,
daily bars, seasonality, key statistics, ratios, financial statements, ownership, insider activity,
corporate actions, analyst ratings and peer comparison.

**One analysis engine.** Indicators, 16 candlestick patterns, multi-timeframe alignment, 9 strategy
presets, backtests with walk-forward validation, universe scans, and TradingView Pine generation —
all over the same series grammar, so the Pine you paste into TradingView fires on the condition that
was actually measured.

**Your account.** Watchlists and saved screens, read and edited, with every write verified by
reading the account back.

**Your chart.** Read and draw on your real Stockbit chart, in your own logged-in browser.

**Automation.** Eight workflows, also offered as MCP prompts. An alert daemon that keeps watching
while no client is open, delivering to a log, a desktop notification, a webhook and Telegram.

![A daily chart with moving averages, Bollinger bands, RSI and MACD](docs/images/price-chart-sample.svg)

<sub>What `price_chart` returns. Synthetic data.</sub>

### Why not a TradingView MCP?

| | TradingView | Stockbit MCP |
|---|---|---|
| IDX broker-level flow | none | the core of it |
| Data access | drives a chart GUI | a JSON API, read directly |
| Your portfolio | no | yes, with your own session |
| Order entry | no | yes, confirm-gated and off by default |
| Indonesian corporate data | thin | financials, ownership, corporate actions, IPO pipeline |

## Installation

**Claude Code**

```bash
claude mcp add --scope user stockbit -- npx -y stockbit-mcp
```

**Claude Desktop** — `claude_desktop_config.json`:

```json
{ "mcpServers": { "stockbit": { "command": "npx", "args": ["-y", "stockbit-mcp"] } } }
```

On Windows, npx needs a shell:

```json
{ "mcpServers": { "stockbit": { "command": "cmd", "args": ["/c", "npx", "-y", "stockbit-mcp"] } } }
```

**Claude Desktop Extension** — download the latest `stockbit-mcp-*.mcpb` from
[Releases](https://github.com/INo-xious/stockbit-mcp/releases) and double-click it.

**Cursor** — `~/.cursor/mcp.json`. Cursor stops at 40 tools and the default `core` profile is
exactly 40, so nothing extra is needed — though that leaves no room for a second MCP server, and
running one means a narrower list (`STOCKBIT_TOOLS=market,bandarmology`, say):

```json
{ "mcpServers": { "stockbit": { "command": "npx", "args": ["-y", "stockbit-mcp"] } } }
```

**VS Code** — `.vscode/mcp.json`. Its cap is 128; the default fits with room to spare:

```json
{ "servers": { "stockbit": { "type": "stdio", "command": "npx", "args": ["-y", "stockbit-mcp"] } } }
```

**Windsurf** — `~/.codeium/windsurf/mcp_config.json`, same shape as Claude Desktop.

**Codex CL