MAX MCP Server
bistin/max-mcp-server
Integração com MAX Exchange para análise e trading via Claude
Ver no GitHubServidor MCP que expõe a API REST V3 da MAX Exchange (MaiCoin) como ferramentas para agentes Claude. Permite consultar dados de mercado, ler conta e, quando habilitado, executar operações de trading com autenticação HMAC-SHA256.
Instalação
npx convez-ai bistin/max-mcp-server1 comando no terminal: detecta o formato do repositório (marketplace ou plugin avulso) e instala via Claude Code. Requer Node 18+ e o Claude Code instalado.
Métricas
Casos de uso
- Consultar dados públicos de mercado (tickers, order books, klines)
- Acessar histórico de contas e operações com credenciais API
- Executar ordens de compra/venda e gerenciar m-wallet (quando habilitado)
Veredito

MCP server bem estruturado para integração com MAX Exchange, com controle granular de permissões (leitura/escrita) via variáveis de ambiente. Documentação clara e avisos apropriados sobre risco em operações reais.
README
A tradução para o português deste README ainda está na fila.
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
| Group | Needs | Tools |
|---|---|---|
| Public market data | — | get_markets, get_currencies, get_server_timestamp, calibrate_time, get_ticker, get_tickers, get_order_book, get_klines, get_public_trades, get_index_prices, get_historical_index_prices, get_borrowing_interest_rates, get_borrowing_limits |
| Account / history (read) | API key+secret | get_user_info, get_accounts, get_order, get_open_orders, get_closed_orders, get_order_history, get_order_trades, get_my_trades, get_deposits, get_deposit, get_deposit_address, get_withdrawals, get_withdrawal, get_withdraw_addresses, get_rewards, get_internal_transfers, get_converts, get_convert |
| M-Wallet (read) | API key+secret | get_ad_ratio, get_loans, get_interests, get_liquidations |
| Trading + m-wallet (write) | API key+secret and MAX_ENABLE_TRADING | create_order, cancel_order, cancel_all_orders, create_loan, repay_loan, m_transfer |
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.
Configuration (environment variables)
| Variable | Required for | Notes |
|---|---|---|
MAX_API_KEY | private endpoints | your MAX API access key |
MAX_API_SECRET | private endpoints | your MAX API secret key |
MAX_ENABLE_TRADING | write tools | set to 1/true/yes to register order/loan/transfer tools |
MAX_API_BASE_URL | — | override base URL (default https://max-api.maicoin.com) |
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,
pathmatch, 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 asnull. - Tool gating — write tools hidden unless
MAX_ENABLE_TRADING; flag parsing of1/true/yes(case-insensitive). - Edge cases —
markets[]array params repeated correctly, thecancel_all_orderssafety scope,calibrate_timepropagating 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