@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

1. Sign in to 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:

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

License

MIT © JTX Markets — markets@jtxmarkets.com