crypto_mcp

crypto_mcp

crypto_mcp is a refactor of crypto_bot into a single MCP-first repository.

Python requirement: >=3.11.

For user-facing capability map, see: docs/CAPABILITIES.MD.

What this project does

• Expose deterministic MCP tools over stdio.
• Keep transport contract stable for LLM clients.
• Separate market data (safe/read-only) from trading (gated).
• Keep exchange adapters replaceable.

Architecture

• src/crypto_mcp/mcp_server.py: FastMCP server and tool definitions.
• src/crypto_mcp/agent.py: NL command router mapping prompts to MCP tools.
• src/crypto_mcp/config.py: Typed settings loader with sane defaults and clamps.
• src/crypto_mcp/adapters/binance.py: Binance HTTP adapter abstraction.
• src/crypto_mcp/main.py: Runnable MCP entrypoint.
• tests/: MCP contract, core server, and agent unit tests.

Detailed architecture: docs/ARCHITECTURE.MD.

Capabilities quick table

| Area | What it does | Main MCP tools | |---|---|---| | Runtime health | Reports service state, limits, mode, exchanges | health | | Exchange inventory | Lists adapter-backed exchanges | list_exchanges | | Market data | Fetches ticker prices and symbol lists | get_price, list_exchange_symbols | | Guarded execution | Submits demo orders with explicit confirmation gate | submit_demo_order, confirm_pending_order | | NL routing | Maps natural language to MCP tool calls | crypto-mcp-agent |

Design pattern references taken from polymarket_mcp:

• deterministic tool envelope: {ok, tool, ...}
• bounded limits for list/read tools
• safety confirmation flow for trade tools
• split entrypoint (main.py) from MCP server implementation

Quickstart

python -m venv .venv
source .venv/bin/activate
pip install -e ".[dev]"
cp .env.example .env
python -m pytest
crypto-mcp-server
# separate terminal
crypto-mcp-agent

Setup path-style variant:

cd /path/to/crypto_mcp
python -m venv .venv
source .venv/bin/activate
pip install -e ".[dev]"
cp .env.example .env

Alternative module runner:

python -m crypto_mcp.main
crypto-mcp

Safety defaults

• DRY_RUN=true

Default path is non-live demo execution.

Run MCP server locally

Stdio server (local MCP clients):

crypto-mcp-server

For MCP Inspector debugging:

npx @modelcontextprotocol/inspector python -m crypto_mcp.main

Do not write print() logs inside stdio server paths. Use logging to stderr.

Available MCP tools:

• health
• list_exchanges
• get_price
• list_exchange_symbols
• submit_demo_order
• confirm_pending_order

Tool response envelope is consistent:

• ok: boolean
• tool: tool name
• error + error_category on failures
• tool-specific payload under payload

MCP limits are controlled by:

• MCP_DEFAULT_LIMIT
• MCP_MAX_LIMIT
• MCP_CONTEXT_MODE (shared or request)

Order safety controls are controlled by:

• DRY_RUN
• REQUIRE_CONFIRMATION_ABOVE_USD

Connect this MCP to clients

Use path placeholders:

• path/to/crypto_mcp = repository root.
• path/to/crypto_mcp/.venv/bin/python = project interpreter.

GitHub Copilot (VS Code Agent Mode)

Add MCP server config in your VS Code MCP settings JSON:

{
  "mcpServers": {
    "crypto-mcp": {
      "command": "python",
      "args": ["-m", "crypto_mcp.main"],
      "cwd": "path/to/crypto_mcp",
      "env": {
        "PYTHONPATH": "src"
      }
    }
  }
}

If your environment requires venv binary, use:

{
  "command": "path/to/crypto_mcp/.venv/bin/python",
  "args": ["-m", "crypto_mcp.main"]
}

Claude Desktop

Edit Claude Desktop MCP config and add:

{
  "mcpServers": {
    "crypto-mcp": {
      "command": "path/to/crypto_mcp/.venv/bin/python",
      "args": ["-m", "crypto_mcp.main"],
      "cwd": "path/to/crypto_mcp",
      "env": {
        "PYTHONPATH": "src"
      }
    }
  }
}

Restart Claude Desktop after changes.

OpenCode

OpenCode can run MCP from command config. Add server entry in your OpenCode MCP configuration:

{
  "mcpServers": {
    "crypto-mcp": {
      "command": "path/to/crypto_mcp/.venv/bin/python",
      "args": ["-m", "crypto_mcp.main"],
      "cwd": "path/to/crypto_mcp",
      "env": {
        "PYTHONPATH": "src"
      }
    }
  }
}

Then restart OpenCode session and verify tools:

• health
• list_exchanges
• get_price
• list_exchange_symbols
• submit_demo_order
• confirm_pending_order

OpenCode install and usage:

# install OpenCode (example)
npm install -g opencode-ai

# verify installation
opencode --version

# start session in this repository
cd path/to/crypto_mcp
opencode

Inside OpenCode:

• ensure MCP server crypto-mcp is connected.
• run a quick tool check with health.
• ask natural language command examples:
• "get btcusdt price"
• "list 20 symbols"
• "buy 50 btcusdt"

Environment

Copy .env.example to .env and update values.

• MCP_DEFAULT_LIMIT, MCP_MAX_LIMIT
• MCP_CONTEXT_MODE (shared or request)
• DRY_RUN (true/false)
• EXCHANGES_ENABLED (binance default)
• GEMINI_API_KEY (optional, used by local NL routing layer)
• BINANCE_API_BASE_URL
• BINANCE_API_KEY, BINANCE_API_SECRET
• REQUIRE_CONFIRMATION_ABOVE_USD

For this task, an empty .env file exists and is safe because defaults are clamped.

What this MCP can do

Read-only tools:

• health: service status, context mode, limits, enabled exchanges.
• list_exchanges: list adapter-backed exchanges.
• get_price: fetch ticker price for symbol/exchange.
• list_exchange_symbols: bounded symbol list with clamp.

Trading flow tools (safety-gated):

• submit_demo_order: validates side/symbol/size and creates pending confirmation above threshold.
• confirm_pending_order: executes pending order if valid and not expired.

Order confirmation flow:

1. Call submit_demo_order.
2. If payload has status=pending_confirmation, capture confirmation_id.
3. Call confirm_pending_order(confirmation_id).

Contract:

• deterministic response envelope: {ok, tool, payload} on success.
• deterministic error envelope: {ok, tool, error, error_category} on failure.
• live trading intentionally disabled: returns live_trading_not_implemented when DRY_RUN=false.

Safety Notes

• submit_demo_order never executes live orders; with DRY_RUN=false it returns live_trading_not_implemented.
• submit_demo_order requires explicit confirmation for large notional.
• response shape never raises raw exceptions to MCP caller; errors are categorized.

Tests

python -m pytest

Important notes

• Local MCP stdio transport must keep stdout clean JSON-RPC only.
• This project is starter infrastructure. Not trading advice.
• Add stronger risk modules before real funds.

Known improvement areas (scan summary)

• Add adapter-level symbol tradability validation before order acceptance.
• Replace broad internal exception mapping with sanitized provider error codes.
• Add confirmation-expiry regression tests at MCP wrapper level.
• Add optional HTTP transport runner for remote clients.