@jtxmarkets/mcp-server

Model Context Protocol server for JTX Markets — 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

Sign in to staging-app.jtxmarkets.com (or the production dashboard once it's live)
Go to /account/api → Additional API Keys → + Create API Key
Scope: Read — the MCP server can't submit orders. This is Phase 1.
(Optional) Add your machine's public IP to the IP allowlist
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:

{
  "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

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