# @jtxmarkets/mcp-server

Model Context Protocol server for [JTX Markets](https://jtxmarkets.com) — query your account and market data from Claude Desktop (and other MCP-compatible clients) in plain English.

> **Phase 1 (this release): read-only.** Positions / orders / trades / balance / funding / market data. Trade-placement tools land in Phase 2.

## Quick start

### 1. Create a Read-scoped API key

1. Sign in to [staging-app.jtxmarkets.com](https://staging-app.jtxmarkets.com) (or the production dashboard once it's live)
2. Go to `/account/api` → **Additional API Keys** → **+ Create API Key**
3. **Scope: Read** — the MCP server can't submit orders. This is Phase 1.
4. (Optional) Add your machine's public IP to the **IP allowlist**
5. Copy the `api_key` and `secret` — the secret is shown **only once**

### 2. Find your Client ID

Your engine `client_id` is on `/account/overview` under the "API Info" section, or you can copy it from your dashboard URL.

### 3. Add to Claude Desktop config

Open `claude_desktop_config.json`:

- macOS: `~/Library/Application Support/Claude/claude_desktop_config.json`
- Windows: `%APPDATA%\Claude\claude_desktop_config.json`

Add an `mcpServers.jtx-markets` entry:

```jsonc
{
  "mcpServers": {
    "jtx-markets": {
      "command": "npx",
      "args": ["-y", "@jtxmarkets/mcp-server"],
      "env": {
        "JTX_MARKETS_API_KEY":    "your-api-key-here",
        "JTX_MARKETS_API_SECRET": "your-api-secret-here",
        "JTX_MARKETS_CLIENT_ID":  "11111111-1111-1111-1111-111111111111",
        "JTX_MARKETS_ENV":        "production"
      }
    }
  }
}
```

### 4. Restart Claude Desktop

Open a new chat, click the tools icon, and you should see **jtx-markets** listed with a green dot.

## Tools (Phase 1 — read-only)

| Tool | Purpose |
|---|---|
| `get_balance` | Balance / Available / Withdrawable / Locked / uPNL / rPNL with plain-English explanations of what each number means |
| `get_positions` | Open positions with entry, mark, uPNL, liquidation price |
| `get_orders` | Open (resting) orders — symbol, side, type, price, size, id |
| `get_trades` | Recent fills. Optional `symbol` filter + `limit` (default 25) |
| `get_funding_history` | Funding payments received or paid |
| `list_markets` | Every listed symbol with mark + 24h volume |
| `get_market_summary` | Mark / funding rate / next funding / open interest / 24h volume for one symbol |

### Example prompts

- *"How much can I withdraw right now?"* — calls `get_balance`, distinguishes Available from Withdrawable
- *"Show me my open ETH-PERP positions"* — calls `get_positions`
- *"Which of my open orders are furthest below the mark?"* — combines `get_orders` + `get_market_summary`
- *"Total funding received this month on BTC-PERP?"* — calls `get_funding_history` and sums

## Environment variables

| Name | Required | Default | Notes |
|---|---|---|---|
| `JTX_MARKETS_API_KEY` | ✅ | — | Public API key from `/account/api` |
| `JTX_MARKETS_API_SECRET` | ✅ | — | HMAC-SHA384 secret; shown once at key creation |
| `JTX_MARKETS_CLIENT_ID` | ✅ | — | Engine client_id UUID |
| `JTX_MARKETS_ENV` |  | `production` | `production` (default). `staging` will resolve once the staging engine host is provisioned. |
| `JTX_MARKETS_BASE_URL` |  | derived from `JTX_MARKETS_ENV` | Override for self-host / testing |

Default is `production` because staging DNS has not yet been provisioned. Once a `staging-engine.jtxmarkets.com` host exists you can flip to `staging` first to test against non-live money.

## Safety notes

- **This is Phase 1.** It cannot place, modify, or cancel orders. It cannot withdraw. It literally does not have those endpoints wired up.
- **API keys are scoped.** The recommended `Read` scope is enforced by the engine on every request (perp-engine auth middleware). If a key is compromised, a `Read` key still can't drain funds — worst case is disclosure of account state.
- **Withdrawals never touch MCP.** They require email verification code + TOTP + admin approval on the dashboard. That flow does not translate to natural language and never will.
- Do not share a chat containing active JTX Markets tool calls — it exposes account state to whoever sees the transcript.

## Development

```bash
npm install
npm test              # 34 tests, all TDD-first
npm run build         # emits dist/
```

## License

MIT © JTX Markets — `markets@jtxmarkets.com`