bitmate-mcp

MCP (Model Context Protocol) server for Bitmate — AI-agent-native control of an algorithmic trading platform. Lets Claude, Cursor, Windsurf, and 20+ other MCP-compatible agents run the full Bitmate workflow: discover strategies, backtest, validate robustness, build portfolios, and deploy to live paper trading.

This npm package is a thin TypeScript proxy that bridges your agent's stdio transport to Bitmate's remote MCP endpoint at https://api.bitmate.ai/mcp. Authentication is OAuth 2.1 with PKCE — no API keys to copy-paste.

Quick start (two commands)

# 1. Auto-detect your AI tool(s) and write the right config stanza
npx bitmate-mcp setup

# 2. Sign in via browser — stores an OAuth token at ~/.bitmate/token
npx bitmate-mcp login

Restart your AI tool(s). That's it.

What setup does

Detects and configures every supported client in one pass. Writes the correct config file in the right schema for each tool, idempotently (safe to re-run, safe to run alongside other MCP servers).

Supported clients:

| Family | Tools | |---|---| | Claude | Claude Desktop, Claude Code | | Editors | Cursor, Windsurf, VS Code, GitHub Copilot, JetBrains IDEs, Visual Studio, Zed, Neovim (mcphub.nvim) | | VS Code extensions | Cline, Roo Code, Continue | | CLIs | Gemini CLI, Gemini Code Assist, OpenAI Codex CLI, Amazon Q CLI | | Apps | Goose, Amp, 5ire, LM Studio, Kiro, Antigravity |

Tools that are GUI-configuration-only (Warp, Cherry Studio, Augment Code) are called out at the end with copy-pasteable snippets.

What login does

Runs the OAuth 2.1 Authorization Code + PKCE flow:

1. Discovers endpoints via /.well-known/oauth-authorization-server.
2. Registers a fresh public client with Dynamic Client Registration.
3. Opens your browser to the Bitmate consent page.
4. You sign in with your Bitmate account and approve the scopes.
5. A loopback server on 127.0.0.1 catches the auth code.
6. Exchanges code → access + refresh token, persisted to ~/.bitmate/token (chmod 600).

The proxy picks up the token on next start and pre-emptively refreshes it when within two minutes of expiry.

Legacy mode (API key)

If you have a long-lived bm_... API key and want to skip the OAuth flow (CI, headless servers, one-off scripts):

export BITMATE_API_KEY=bm_your_key_here
npx bitmate-mcp setup         # embeds the key into each client config

Or configure the client manually:

{
  "mcpServers": {
    "bitmate": {
      "command": "npx",
      "args": ["-y", "bitmate-mcp"],
      "env": { "BITMATE_API_KEY": "bm_..." }
    }
  }
}

The proxy accepts either a token file or BITMATE_API_KEY. Token file wins when both are present.

Environment variables

| Variable | Default | Purpose | |---|---|---| | BITMATE_API_URL | https://api.bitmate.ai/mcp/ | Remote MCP endpoint | | BITMATE_ISSUER_URL | origin of BITMATE_API_URL | OAuth issuer (for login) | | BITMATE_OAUTH_SCOPES | mcp:read mcp:optimize mcp:trade | Space-separated scopes requested at login | | BITMATE_API_KEY | — | Legacy opaque bearer; overridden by token file if present |

Troubleshooting

no Bitmate credentials found → Run npx bitmate-mcp login or set BITMATE_API_KEY.

Token refresh failed → Your refresh token expired or was revoked. Run npx bitmate-mcp login again.

state mismatch (possible CSRF) during login → Stale browser tab. Close it and re-run npx bitmate-mcp login.

Failed to connect to Bitmate API → Check BITMATE_API_URL and your network. The server-side error message (after the colon) usually points at the real cause.

Documentation

• MCP guide
• Tool reference
• OAuth operator runbook

License

MIT — see the top-level repository for the full text.