# midas-mcp

An [MCP](https://modelcontextprotocol.io) server for the **Midas** brokerage
([atlas.getmidas.com](https://atlas.getmidas.com/)), so an AI assistant can read your
portfolio and place orders on BIST and US markets.

Midas has no public API. This server drives the Atlas web app with
[Playwright](https://playwright.dev): it keeps one authenticated browser session alive
and issues the same GraphQL calls the web app itself makes, from inside the page so the
session cookies are attached automatically.

> **This places real orders with real money.** Read the safety section before using it.

## Tools

| Tool | Arguments | What you get |
| --- | --- | --- |
| `get_portfolio` | – | Total value in TRY, today's P/L, cash and buying power per account |
| `get_assets` | – | Every open position: quantity, average cost, price, market value, P/L |
| `get_asset_price` | `symbol`, optional `currency` | Last price, previous close, % change, session status |
| `get_asset_info` | `symbol` | Instrument name, market and description, plus current price |
| `buy_asset` | `symbol`, `quantity`, optional `limit_price` | Places a buy order, returns the order id and status |
| `sell_asset` | `symbol`, `quantity`, optional `limit_price` | Places a sell order, returns the order id and status |
| `get_pending_orders` | `symbol` | Orders still waiting to execute, with their ids |
| `cancel_order` | `order_id`, `symbol` | Cancels a pending order |

Omitting `limit_price` places a market order. Symbols are resolved by search, so both
tickers (`TUCLK`) and names work; BIST and US instruments are both supported.

## Safety

Every order is checked **before** it reaches Midas:

- **Value cap** — the order's estimated value is converted to TRY (Midas will quote any
  instrument in TRY) and refused if it exceeds `MAX_ORDER_VALUE_TRY`, which defaults to
  5000. One cap therefore covers both the TRY and USD accounts.
- **Price band** — limit prices outside the instrument's daily band are refused locally
  rather than bounced by the exchange.
- **Position check** — sells larger than your sellable quantity are refused.
- **Fractional check** — fractional quantities are refused for instruments that don't
  support them.

`cancel_order` exists so a mistake can be undone immediately. Note that BIST trades
10:00–18:00 Turkey time; orders placed outside the session queue for the next one, which
means they can be cancelled before they ever reach the exchange.

## Setup

Requires Node.js 20+.

```bash
git clone https://github.com/<you>/midas-mcp.git
cd midas-mcp
npm install
npx playwright install chromium
cp .env.example .env    # then fill in your credentials
npm run build
```

`.env`:

```ini
MIDAS_PHONE=5XXXXXXXXX      # Turkish mobile number, no country code
MIDAS_PASSWORD=your-password
MAX_ORDER_VALUE_TRY=5000    # refuse any order estimated above this, in TRY
HEADLESS=true
```

`.env` and the browser profile in `.midas-session/` are both gitignored — they hold your
credentials and session cookies, so keep them out of version control.

### First login

Midas requires approving a push notification in the Midas mobile app, so the first login
has to be interactive:

```bash
npm run login          # opens a visible browser, then approve the prompt on your phone
```

The session is saved to `.midas-session/` and reused afterwards, so this is a one-off
until the session expires. Only one process can use that profile at a time — stop the
MCP server before running `npm run login`.

Verify it works:

```bash
npm run smoke          # prints your portfolio, positions and a quote
```

### Register with Claude Code

```bash
claude mcp add midas -- node /absolute/path/to/midas-mcp/dist/index.js
```

Or, for any MCP client that reads a JSON config:

```json
{
  "mcpServers": {
    "midas": {
      "command": "node",
      "args": ["/absolute/path/to/midas-mcp/dist/index.js"]
    }
  }
}
```

## How it works

`src/session.ts` launches a persistent Chromium profile and handles login. Auth is
entirely cookie-based, so `src/api.ts` runs each GraphQL request via `page.evaluate`
inside the authenticated page rather than reimplementing the token flow.

Two details are easy to miss when working on this:

- The API gateway requires an `x-midas-rid` header. It is a stable per-profile request
  id generated by the web app, so the session observes it on the app's own requests
  instead of trying to recompute it.
- The gateway routes on `x-apollo-operation-name`, which must be the **root field name**,
  not the operation name. When a document's first selection is an alias (as in
  `OverviewAllPositions`), the real field name has to be passed explicitly.

Headless Chromium is rejected with a 403 unless it presents a normal user agent and
client hints; `session.ts` sets these.

`scripts/` holds the tooling used to map the API, kept for when Midas changes it:
`browser-daemon.ts` (logging browser with a CDP port), `analyze.ts` (summarise captured
GraphQL traffic), `dump-panel-bundles.ts` (download lazy-loaded chunks), and
`extract-ops.ts` / `extract-document.ts` (recover GraphQL documents from the minified
bundle's embedded AST — introspection is disabled server-side).

## Verifying trading end-to-end

`src/order-test.ts` places one real single-share order and cancels it immediately. It
also checks that the value cap rejects an oversized order. It refuses to run without an
explicit confirmation:

```bash
CONFIRM_REAL_ORDER=yes node dist/order-test.js CANTE 1.08 BUY
CONFIRM_REAL_ORDER=yes node dist/order-test.js TUCLK 4.04 SELL
```

Pick a limit price at the far end of the daily band so the order cannot fill, and run it
while the market is closed for extra margin.

## Disclaimer

Unofficial, not affiliated with or endorsed by Midas. It depends on undocumented
internal endpoints that can change without notice. You are responsible for every order
it places. Use at your own risk.

## License

MIT