# jcwleo/ccxt-mcp-server architecture

> Architecture diagram of the GitHub repository jcwleo/ccxt-mcp-server, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-05-21). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/jcwleo/ccxt-mcp-server
- Repository: https://github.com/jcwleo/ccxt-mcp-server

## Overview

##### 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.

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% External Entities
    MCPClient["MCP Client(s)"]:::external
    ExchangeAPI["Exchange API Endpoints"]:::external

    %% Async Runtime Boundary
    subgraph "Asyncio Event Loop"
        direction TB
        FastMCP["FastMCP Server"]:::core
        Dispatcher["Tool Registry & Dispatcher"]:::core
        CCXTClient["CCXT Async Client\n(ccxt.async_support)"]:::core
    end

    %% Infrastructure
    Config["Configuration & Secrets"]:::infra

    %% Project Dependencies
    subgraph "Project Dependencies"
        direction TB
        PyProj["pyproject.toml"]:::infra
        ReqTxt["requirements.txt"]:::infra
    end

    %% Connections
    MCPClient -->|"MCP connect/register\nMCP Request/Response"| FastMCP
    FastMCP -->|"invoke tool\nMCP Request"| Dispatcher
    Dispatcher -->|"pydantic validation"| Dispatcher
    Dispatcher -->|"async call"| CCXTClient
    CCXTClient -->|"HTTPS JSON / WebSocket"| ExchangeAPI
    ExchangeAPI -->|"JSON response"| CCXTClient
    CCXTClient -->|"result/error"| Dispatcher
    Dispatcher -->|"MCP Response"| FastMCP
    FastMCP -->|"MCP Response"| MCPClient

    %% Config and Dependencies
    Config -->|used by| CCXTClient
    Config -->|used by| FastMCP
    PyProj -->|dependencies| FastMCP
    ReqTxt -->|dependencies| FastMCP

    %% Click events
    click FastMCP "https://github.com/jcwleo/ccxt-mcp-server/blob/main/mcp_server.py"
    click Dispatcher "https://github.com/jcwleo/ccxt-mcp-server/blob/main/mcp_server.py"
    click CCXTClient "https://github.com/jcwleo/ccxt-mcp-server/blob/main/mcp_server.py"
    click Config "https://github.com/jcwleo/ccxt-mcp-server/blob/main/mcp_server.py"
    click PyProj "https://github.com/jcwleo/ccxt-mcp-server/blob/main/pyproject.toml"
    click ReqTxt "https://github.com/jcwleo/ccxt-mcp-server/blob/main/requirements.txt"

    %% Styles
    classDef external fill:#ccffcc,stroke:#333,stroke-width:1px
    classDef core fill:#add8e6,stroke:#333,stroke-width:1px
    classDef infra fill:#ffcc99,stroke:#333,stroke-width:1px
```
