Binance MCP Server

# CLAUDE.md This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository. ## Development Commands ### Package Management - `rye sync` - Install dependencies (preferred) - `uv sync` - Alternative dependency installation ### Running the Server - `rye run mcp` - Run MCP server (preferred method) - `mcp` - Run if virtualenv is activated - `python -m src.binance_mcp.main` - Development mode from project root ### Code Quality - `rye run ruff check src/` - Lint the codebase - `rye run ruff format src/` - Format code - `rye run ruff check --fix src/` - Auto-fix lint issues ## Architecture Overview This is a FastMCP server providing cryptocurrency exchange integration and datetime utilities. The architecture follows a layered approach: ### Core Components **FastMCP Integration**: Built on FastMCP 2.x framework with support for both HTTP and STDIO transports. Tools are exposed via `@mcp.tool()` decorators in `main.py`. **Configuration Layer**: `settings.py` uses Pydantic Settings with environment variable loading via python-dotenv. Supports optional Binance API credentials and Logfire observability. **Client Management**: `client.py` provides an LRU-cached Binance client factory that handles API authentication and connection pooling. **Response Models**: `models.py` defines Pydantic models for all tool responses with proper field validation and aliases for external API compatibility. **Tool Implementation**: Tools are separated into modules under `tools/` with `timestamp.py` containing datetime and Binance time operations. ### Key Design Patterns **Environment-Based Configuration**: All configuration through environment variables with `.env` file support. No hardcoded credentials or settings. **Lazy Client Initialization**: Binance client is created on-demand with LRU caching to handle API rate limits efficiently. **Validated Responses**: All tool responses use Pydantic models ensuring type safety and automatic JSON serialization. **Transport Agnostic**: Server supports both STDIO (for MCP clients like Claude Desktop) and HTTP (for web integration) via configuration. ### Tool Categories **DateTime Tools**: `get_current_datetime` provides system time in ISO8601 format. **Binance Connectivity**: `binance_test_connectivity` tests API reachability without authentication. **Binance Time Sync**: `get_binance_server_time` retrieves exchange server time for trading operations. ## Environment Setup Create `.env` from `.env.example`. Binance API credentials are optional - basic tools work without authentication. Logfire token enables observability but is not required for core functionality. ## Ruff Configuration Uses Python 3.13 target with 120 character line length. Enforces timezone-aware datetime usage, pathlib over os.path, and comprehensive linting rules. Auto-fixes most issues when run with `--fix`. ## MCP Integration Server name is "binance-mcp" and provides three tools. For Claude Desktop integration, use STDIO transport. For web applications, use HTTP transport on configurable port (default 8000).