Submit
IBM

ChukMCPServer

Community IBM
Updated

ChukMCPServer

The fastest, most developer-friendly MCP server framework for Python.

Build production-ready Model Context Protocol servers in minutes with decorator-based tools, zero-config deployment, and world-class performance.

PyPIPythonTestsCoverageLicense

from chuk_mcp_server import tool, run

@tool
def add(a: int, b: int) -> int:
    """Add two numbers together."""
    return a + b

run()  # That's it! Server running on stdio

⚡ Quick Start

Installation

# Basic installation
pip install chuk-mcp-server

# With optional features
pip install chuk-mcp-server[google_drive]  # Google Drive OAuth

Your First Server (30 seconds)

Option 1: Use the scaffolder (recommended)

uvx chuk-mcp-server init my-server
cd my-server
uv run my-server

Option 2: Write it yourself (5 lines of code)

from chuk_mcp_server import tool, run

@tool
def greet(name: str) -> str:
    """Greet someone by name."""
    return f"Hello, {name}!"

run()

Option 3: Add to Claude Desktop (instant integration)

uvx chuk-mcp-server init my-server --claude
# Automatically adds to claude_desktop_config.json

Use with Claude Desktop

Add to ~/Library/Application Support/Claude/claude_desktop_config.json:

{
  "mcpServers": {
    "my-server": {
      "command": "uv",
      "args": ["run", "my-server"]
    }
  }
}

Restart Claude Desktop - your tools are now available!

🚀 Why ChukMCPServer?

  • 🏆 World-Class Performance: 36,000+ requests/second, <3ms overhead
  • 📋 Full MCP 2025-11-25: Complete conformance with the latest MCP specification
  • 🤖 Claude Desktop Ready: Zero-config stdio transport
  • ⚡ Zero Configuration: Smart defaults detect everything automatically
  • 🔐 OAuth 2.1 Built-In: Full OAuth support with @requires_auth decorator
  • ☁️ Cloud Native: Auto-detects GCP, AWS, Azure, Vercel
  • 🔒 Type Safe: Automatic schema generation from Python type hints
  • 🏷️ Tool Annotations: read_only_hint, destructive_hint, idempotent_hint, open_world_hint
  • 📊 Structured Output: output_schema on tools with typed structuredContent responses
  • 🎨 Icons: Icons on tools, resources, prompts, and server info
  • 📦 Dual Transport: STDIO + Streamable HTTP (with GET SSE streams), both with bidirectional support
  • 🧩 Full Protocol Surface: Sampling, elicitation, progress, roots, subscriptions, completions, tasks, cancellation
  • 🛡️ Production Hardened: Rate limiting, request validation, graceful shutdown, thread safety, health probes
  • 🧪 ToolRunner: Test tools without transport overhead
  • 📄 OpenAPI: Auto-generated OpenAPI 3.1.0 spec at /openapi.json

📚 Documentation

Full documentation available at: https://IBM.github.io/chuk-mcp-server/

🎯 Core Features

Decorators for Everything

from chuk_mcp_server import tool, resource, resource_template, prompt, requires_auth

@tool(read_only_hint=True, idempotent_hint=True,
      output_schema={"type": "object", "properties": {"result": {"type": "integer"}}})
def calculate(x: int, y: int) -> dict:
    """Perform calculations with structured output."""
    return {"result": x + y}

@resource("config://settings",
          icons=[{"uri": "https://example.com/gear.svg", "mimeType": "image/svg+xml"}])
def get_settings() -> dict:
    """Access configuration."""
    return {"theme": "dark", "version": "1.0"}

@resource_template("users://{user_id}/profile")
def get_user_profile(user_id: str) -> dict:
    """Parameterized resource template (RFC 6570)."""
    return {"user_id": user_id, "name": "Example User"}

@prompt
def code_review(code: str, language: str) -> str:
    """Generate code review prompt."""
    return f"Review this {language} code:\n{code}"

@tool
@requires_auth()
async def publish_post(content: str, _external_access_token: str | None = None) -> dict:
    """OAuth-protected tool."""
    # Token automatically injected and validated
    ...

HTTP Mode for Web Apps

from chuk_mcp_server import ChukMCPServer

mcp = ChukMCPServer(
    name="my-api",
    description="My production API server",
    icons=[{"uri": "https://example.com/icon.png", "mimeType": "image/png"}],
    website_url="https://example.com",
)

@mcp.tool
async def process_data(data: str) -> dict:
    return {"processed": data}

mcp.run(host="0.0.0.0", port=8000)  # HTTP server

MCP Apps — Rich UI Views in Claude.ai

Render interactive charts, maps, tables, and more directly in Claude.ai using MCP Apps structured content.

from chuk_mcp_server import ChukMCPServer

mcp = ChukMCPServer(name="my-view-server", version="1.0.0")

@mcp.tool(
    name="show_chart",
    description="Show sales data as a chart.",
    meta={
        "ui": {
            "resourceUri": "ui://my-view-server/chart",
            "viewUrl": "https://chuk-mcp-ui-views.fly.dev/chart/v1",
        }
    },
)
async def show_chart(chart_type: str = "bar") -> dict:
    return {
        "content": [{"type": "text", "text": "Sales chart."}],
        "structuredContent": {
            "type": "chart",
            "version": "1.0",
            "title": "Q1 Sales",
            "chartType": chart_type,
            "data": [{"label": "Revenue", "values": [
                {"label": "Jan", "value": 4200},
                {"label": "Feb", "value": 5100},
                {"label": "Mar", "value": 4800},
            ]}],
        },
    }

mcp.run()

How it works:

  • meta.ui.resourceUri — a ui:// URI identifying the view
  • meta.ui.viewUrl — HTTPS URL serving the view's HTML/JS bundle
  • The server automatically registers an MCP resource at the resourceUri that fetches the HTML from viewUrl
  • The server automatically enables the experimental capability
  • Claude.ai reads the HTML via resources/read, renders it in an iframe, and passes structuredContent as the data payload

See examples/mcp_apps_view_example.py for a complete example.

Cloud Deployment (Auto-Detection)

# Same code works everywhere - cloud platform auto-detected!
from chuk_mcp_server import tool, run

@tool
def my_tool(x: int) -> int:
    return x * 2

run()  # Automatically adapts to GCP, AWS, Azure, Vercel, etc.

Server Composition (Mix Local & Remote Tools)

Combine multiple MCP servers into one unified interface. Import tools from local Python modules or remote servers (STDIO/HTTP/SSE):

# config.yaml
composition:
  import:
    # Local Python module
    - name: "echo"
      type: "module"
      module: "chuk_mcp_echo.server:echo_service"
      prefix: "echo"

    # Remote MCP server via STDIO
    - name: "fetch"
      type: "stdio"
      command: "uvx"
      args: ["mcp-server-fetch"]
      prefix: "fetch"

    # Remote MCP server via HTTP
    - name: "weather"
      type: "http"
      url: "https://api.weather.com/mcp"
      prefix: "weather"

from chuk_mcp_server import ChukMCPServer

mcp = ChukMCPServer("composed-server")
mcp.load_config("config.yaml")
mcp.run()  # All tools available under unified namespaces

What you get:

  • ✅ Module imports: Direct Python imports (fastest)
  • ✅ STDIO proxy: Connect to subprocess servers (uvx, npx, python -m)
  • ✅ HTTP proxy: Connect to remote HTTP MCP servers
  • ✅ Built-in resilience: Automatic timeouts, retries, circuit breakers (via chuk-tool-processor)
  • ✅ Unified namespace: Tools prefixed by source (e.g., fetch.fetch, echo.echo_text)

🏆 Performance

ChukMCPServer is built for high throughput:

  • 36,348 RPS peak throughput (performance test)
  • 39,261 RPS with max optimizations (ultra test)
  • <3ms overhead per tool call
  • 100% success rate under sustained load

See Performance Benchmarks for detailed results.

📖 Learn More

Real-World Examples

🤝 Contributing

Contributions welcome! See Contributing Guide for details.

📄 License

Apache 2.0 License - see LICENSE file for details.

🔗 Links

MCP Server · Populars

MCP Server · New