max-mcp

An MCP server for the MAX Exchange (MaiCoin) V3 REST API.

Disclaimer. Unofficial and community-maintained. Not affiliated with, endorsed by, or supported by MaiCoin / MAX Exchange. Trading tools move real funds — use at your own risk.

It exposes MAX endpoints as MCP tools so an agent (Claude Code, Claude Desktop, etc.) can query market data, read your account, and — when explicitly enabled — place and cancel orders. The request signing follows the MAX V3 auth scheme: HMAC-SHA256 over a base64 JSON payload, with the nonce echoed in the query/body and path matched exactly (see max_mcp/client.py).

Tools

Write tools are not registered at all unless MAX_ENABLE_TRADING is set, so an agent can't even see them in the default read-only configuration.

Related MCP server: Shioaji MCP Server

Configuration (environment variables)

Public market-data tools work with no credentials.

Install

The package installs a max-mcp console script. The tricky part is where that binary lives: an MCP client (Claude Code / Desktop) launches a fresh process that does not inherit your shell's PATH or any activated virtualenv. So the reliable pattern is to either let uv resolve the environment for you, or point the client at an absolute path to the binary. Pick one of the options below.

Option A — uv (recommended, no install step)

uv can run the server straight from GitHub and manage the environment itself, so there's no PATH to worry about:

# one-off smoke test
uvx --from "git+https://github.com/bistin/max-mcp-server.git" max-mcp

uvx is the command the MCP client will run too (see config sections below), which sidesteps the whole "is it on my PATH" problem.

For local development with uv:

git clone https://github.com/bistin/max-mcp-server.git
cd max-mcp-server
uv sync                 # creates .venv and installs the project + deps
uv run max-mcp          # runs the stdio server inside the managed env

Option B — venv + pip

Standard library virtualenv, no extra tooling:

git clone https://github.com/bistin/max-mcp-server.git
cd max-mcp-server
python3 -m venv .venv
.venv/bin/pip install -e .
.venv/bin/max-mcp       # run via the venv's binary, not a bare `max-mcp`

The venv's binary lives at /abs/path/to/max-mcp-server/.venv/bin/max-mcp (...\.venv\Scripts\max-mcp.exe on Windows). Note that path — you'll give it to the MCP client below. Activating the venv (source .venv/bin/activate) only affects your shell, not the client process, so don't rely on a bare max-mcp working there.

Tip: run command -v max-mcp (or .venv/bin/python -c "import shutil,sys; print(shutil.which('max-mcp'))") to print the absolute path to paste into the configs below.

Register with Claude Code

With uv (Option A) — no install step, uv resolves the env each launch:

claude mcp add max \
  -e MAX_API_KEY=your_key \
  -e MAX_API_SECRET=your_secret \
  -- uvx --from "git+https://github.com/bistin/max-mcp-server.git" max-mcp

With a venv (Option B) — point at the venv's absolute binary path:

claude mcp add max \
  -e MAX_API_KEY=your_key \
  -e MAX_API_SECRET=your_secret \
  -- /abs/path/to/max-mcp-server/.venv/bin/max-mcp

Add -e MAX_ENABLE_TRADING=1 only if you want the agent to place/cancel orders.

Claude Desktop config

Claude Desktop launches the command itself, so the same rule applies: use uvx, or give an absolute path. Pick the block that matches your install.

uv (Option A):

{
  "mcpServers": {
    "max": {
      "command": "uvx",
      "args": [
        "--from",
        "git+https://github.com/bistin/max-mcp-server.git",
        "max-mcp"
      ],
      "env": {
        "MAX_API_KEY": "your_key",
        "MAX_API_SECRET": "your_secret"
      }
    }
  }
}

venv (Option B) — use the absolute path to the venv binary (...\.venv\Scripts\max-mcp.exe on Windows):

{
  "mcpServers": {
    "max": {
      "command": "/abs/path/to/max-mcp-server/.venv/bin/max-mcp",
      "env": {
        "MAX_API_KEY": "your_key",
        "MAX_API_SECRET": "your_secret"
      }
    }
  }
}

Tests

With uv:

uv run --extra test pytest

With a venv:

.venv/bin/pip install -e ".[test]"
.venv/bin/python -m pytest

All HTTP is mocked with respx, so the suite never touches the live API or your account — it's safe to run with real credentials in the environment. The 44 tests cover:

• Signing/headers — nonce in both query and payload, path match, HMAC signature, monotonic nonce under same-millisecond concurrency.

• Request placement — GET params in the query string vs POST/DELETE params in the JSON body; None-valued optionals dropped, never sent as null.

• Tool gating — write tools hidden unless MAX_ENABLE_TRADING; flag parsing of 1/true/yes (case-insensitive).

• Edge cases — markets[] array params repeated correctly, the cancel_all_orders safety scope, calibrate_time propagating upstream errors instead of crashing, error/​network-failure mapping to a structured dict, and the console entry point.

Notes

• All prices/volumes/fees/balances are returned as strings — keep them as decimal strings, never parse to float.

• K-lines return bare numeric arrays [ts, o, h, l, c, v] with unix-second timestamps.

• MAX API errors are returned as {"_http_status": <int>, "success": false, "error": {"code", "message"}} so the agent can read the code/message.

License

Apache-2.0 © bistin