How jcwleo/ccxt-mcp-server works
Project type and purpose
• This is a back-end only MCP (Model Context Protocol) server built in Python.
• Its purpose is to expose CCXT (crypto-exchange) operations as asynchronous “tools” over an MCP interface so that LLMs and other MCP clients can invoke exchange functions (fetch balances, market data, place orders, etc.) in a uniform way.
File structure
• Top-level files:
• mcp_server.py – the single entry point where the FastMCP server, tool definitions, authentication logic, and CCXT client orchestration live.
• pyproject.toml / requirements.txt – project dependencies (FastMCP, ccxt.async_support, pydantic, uv).
• uv.lock – lock file for uv environment.
• There are no separate “frontend” or “backend” directories: it’s a mono-repo Python service.
Key insights from the README
• The server uses FastMCP to register and expose CCXT functions as MCP tools.
• Tools are categorized into public (no auth) and private (requires API key/secret).
• Asynchronous operations (asyncio + ccxt.async_support).
• Uses Python typing.Annotated + pydantic for parameter metadata.
• Clients connect over the default FastMCP networking layer (TCP/port).
Main architectural components
a. MCP Client(s) (External)
• Could be an LLM-based client (Claude, custom), any MCP-compatible process.
b. FastMCP Server
• Listens for MCP connections, handles registration of tools, dispatches incoming tool calls.
c. Tool Registry & Dispatcher
• The layer in mcp_server.py that maps MCP tool names to Python async functions.
• Uses metadata from Annotated + pydantic.Field to validate inputs.
d. CCXT Async Client
• Under the hood, each tool call invokes methods on the CCXT async client objects (e.g., exchange.fetch_balance(), exchange.create_order()).
e. Exchange API Endpoints (External)
• The actual REST/WebSocket endpoints of cryptocurrency exchanges (Binance, Coinbase, etc.).
f. Configuration & Secrets
• API key, secret, passphrase passed into CCXT client instantiation.
• Could be env vars or parameters that the client sends at runtime.
g. Asyncio Event Loop
• Manages concurrency for all async calls (FastMCP + CCXT).
Relationships & data flow
1. MCP Client → FastMCP Server (register/connect)
2. MCP Client sends a tool-invocation request → FastMCP Server
3. FastMCP Server → Tool Dispatcher (validate params via pydantic)
4. Dispatcher → CCXT Async Client method call → Asyncio Event Loop
5. CCXT Async Client → Exchange API over HTTPS/WebSocket
6. Exchange API response → CCXT Async Client → Dispatcher
7. Dispatcher → FastMCP Server → MCP Client (result or error payload)
Architectural patterns & design principles
• Asynchronous, non-blocking I/O: Single event loop handles both MCP protocol and exchange HTTP.
• Layered separation: Protocol layer (FastMCP) vs. business logic (tools) vs. transport (CCXT → exchange).
• Metadata-driven validation: Use of Annotated + pydantic to automatically generate tool schemas.
• Tool classification: Public vs. private operations separated by the presence of authentication credentials.