chuk-mcp

A lean, minimal Python implementation of the Model Context Protocol (MCP).

Brings first-class MCP protocol support to Python — lightweight, async, and spec-accurate from day one.

chuk-mcpgives you a clean, typed, transport-agnostic implementation for bothMCP clients and servers. It focuses on the protocol surface (messages, types, versioning, transports) and leaves orchestration, UIs, and agent frameworks to other layers.

✳️What this is: aprotocol compliance librarywith ergonomic helpers for clients and servers.

⛔What this isn't: a chatbot runtime, workflow engine, or an opinionated application framework.

┌──────────────────────────────────────┐ │ Your AI Application │ │ (Claude, GPT, custom agents) │ └────────────┬─────────────────────────┘ │ MCP Protocol ▼ ┌──────────────────────────────────────┐ │ chuk-mcp Client │ ← You are here │ • Protocol compliance │ │ • Transport (stdio/Streamable HTTP)│ │ • Type-safe messages │ │ • Capability negotiation │ └────────────┬─────────────────────────┘ │ MCP Protocol ▼ ┌──────────────────────────────────────┐ │ chuk-mcp Server (optional) │ │ • Protocol handlers │ │ • Tool/Resource registration │ │ • Session management │ └────────────┬─────────────────────────┘ │ ▼ ┌──────────────────────────────────────┐ │ Your Tools & Resources │ │ (databases, APIs, files, etc) │ └──────────────────────────────────────┘

chuk-mcp provides the protocol layer— connect AI applications to tools and data sources using the standard MCP protocol.

The library itself is organized in layers that you can use at different levels of abstraction:

┌─────────────────────────────────────────┐ │ CLI & Demo Layer │ __main__.py, demos/ ├─────────────────────────────────────────┤ │ Client/Server API │ High-level abstractions ├─────────────────────────────────────────┤ │ Protocol Layer │ Messages, types, features ├─────────────────────────────────────────┤ │ Transport Layer │ stdio, Streamable HTTP ├─────────────────────────────────────────┤ │ Base Layer │ Pydantic fallback, config └─────────────────────────────────────────┘

Most users work with theProtocol Layer(send_functions) andTransport Layer(stdio/HTTP clients), optionally using theClient/Server APIfor higher-level abstractions.

pip install "chuk-mcp[fast-json]" # Automatic with graceful fallback

Benchmark numbers frombenchmarks/json_performance.pycomparing orjson vs stdlib json on realistic MCP messages.*

- High-frequency tool calls— minimal overhead per request
- Real-time agents— sub-5ms protocol latency
- Streaming UIs— near-zero NDJSON chunk overhead
- Tool processors— fast enough to be transparent
- WASM/edge environments— minimal footprint
- High-throughput workloads— proven at scale (seeScaling & Concurrency)

# Install an example MCP server uv tool install mcp-server-sqlite # Run the quick-start example uv run python examples/quickstart_sqlite.py

# hello_mcp.py import anyio from chuk_mcp.server import MCPServer, run_stdio_server from chuk_mcp.protocol.types import ServerCapabilities, ToolCapabilities async def main(): server = MCPServer("hello", "1.0", ServerCapabilities(tools=ToolCapabilities())) async def handle_tools_list(message, session_id): return server.protocol_handler.create_response( message.id, {"tools": [{"name": "hello", "description": "Say hi", "inputSchema": {"type": "object"}}]} ), None server.protocol_handler.register_method("tools/list", handle_tools_list) await run_stdio_server(server) anyio.run(main)

Run it:uv run python hello_mcp.py— or connect any MCP client via stdio!

# Connect to an MCP server via stdio and list tools import anyio from chuk_mcp import StdioServerParameters, stdio_client from chuk_mcp.protocol.messages import send_initialize from chuk_mcp.protocol.messages.tools import send_tools_list async def main(): params = StdioServerParameters(command="uvx", args=["mcp-server-sqlite", "--db-path", "example.db"]) async with stdio_client(params) as (read, write): init = await send_initialize(read, write) tools = await send_tools_list(read, write) print("Server:", init.serverInfo.name) print("Tools:", [t.name for t in tools.tools]) anyio.run(main)

# Local dev (plain HTTP) import anyio from chuk_mcp.transports.http import http_client, HttpClientParameters from chuk_mcp.protocol.messages import send_initialize async def main(): params = HttpClientParameters( url="http://localhost:8989/mcp", timeout_s=30, headers={"Authorization": "Bearer <token>"} ) async with http_client(params) as (read, write): init = await send_initialize(read, write) print("Connected:", init.serverInfo.name) anyio.run(main) # TLS (secure transport) async def main_secure(): params = HttpClientParameters( url="https://mcp.example.com/mcp", timeout_s=30, headers={"Authorization": "Bearer <token>"} ) async with http_client(params) as (read, write): init = await send_initialize(read, write) print("Connected:", init.serverInfo.name) anyio.run(main_secure)

uv add chuk-mcp # core (Python 3.11+ required) uv add "chuk-mcp[pydantic]" # add typed Pydantic models (Pydantic v2 only) uv add "chuk-mcp[http]" # add Streamable HTTP transport extras uv add "chuk-mcp[fast-json]" # add fast JSON (orjson - 4x faster!) uv add "chuk-mcp[full]" # full install with all features

…