mcpserve

Minimal, decorator-based framework for building Model Context Protocol (MCP) servers in Python.

Zero required dependencies. Define tools and resources with simple decorators, and mcpserve handles the JSON-RPC protocol, parameter inference, and stdio transport.

Why?

MCP is the emerging standard for connecting AI assistants to external tools and data. But building an MCP server from scratch means implementing JSON-RPC 2.0 framing, capability negotiation, schema generation, and error handling. mcpserve handles all of that so you can focus on your tool logic.

• Decorator-based — @server.tool() and @server.resource() are all you need
• Type inference — parameter types and optionality are inferred from Python type hints
• Async-ready — supports both sync and async tool handlers
• Zero dependencies — stdlib only for the core library (asyncio + json)
• MCP 2024-11-05 — implements the latest protocol version

Architecture

graph LR
    subgraph "AI Assistant"
        A[LLM Client]
    end

    subgraph "mcpserve"
        B[Stdio Transport] --> C[JSON-RPC Router]
        C --> D[Method Dispatcher]
        D --> E[tools/list]
        D --> F[tools/call]
        D --> G[resources/list]
        D --> H[resources/read]
    end

    subgraph "Your Code"
        I["@server.tool()"]
        J["@server.resource()"]
    end

    A <-->|"stdin/stdout"| B
    F --> I
    H --> J

Quick Start

from mcpserve import Server

server = Server(name="my-tools", version="1.0.0")

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

@server.tool()
def search(query: str, limit: int = 10) -> str:
    """Search for documents matching a query."""
    # Your logic here
    return f"Found {limit} results for: {query}"

@server.resource(uri="status://health", name="Health Check")
def health():
    """Server health status."""
    return "ok"

if __name__ == "__main__":
    server.run()

That's it. Run your server, point an MCP client at it, and your tools are available to the AI.

Installation

pip install mcpserve

Or from source:

git clone https://github.com/AmirNaghibi/mcpserve.git
cd mcpserve
pip install -e .

Usage with Claude Desktop

Add to your claude_desktop_config.json:

{
  "mcpServers": {
    "my-tools": {
      "command": "python",
      "args": ["/path/to/your/server.py"]
    }
  }
}

Features

Tool Registration

Parameters are automatically inferred from type hints:

@server.tool()
def fetch_url(url: str, timeout: int = 30, follow_redirects: bool = True) -> str:
    """Fetch content from a URL."""
    # url: required string
    # timeout: optional integer, default 30
    # follow_redirects: optional boolean, default True
    ...

Supported types: str, int, float, bool, list, dict

Async Tools

@server.tool()
async def slow_operation(input: str) -> str:
    """An async tool that does something time-consuming."""
    await asyncio.sleep(1)
    return f"Processed: {input}"

Resources

Expose data that the AI can read without calling a tool:

@server.resource(uri="docs://readme", name="README", mime_type="text/markdown")
def readme():
    with open("README.md") as f:
        return f.read()

Structured Results

Return rich results when plain text isn't enough:

from mcpserve import ToolResult

@server.tool()
def query_db(sql: str) -> ToolResult:
    try:
        rows = db.execute(sql)
        return ToolResult.json(rows)
    except Exception as e:
        return ToolResult.error(f"Query failed: {e}")

Custom Tool Names

@server.tool(name="web_search", description="Search the internet")
def my_internal_function(query: str) -> str:
    ...

Request Flow

sequenceDiagram
    participant Client as AI Client
    participant Transport as Stdio Transport
    participant Router as JSON-RPC Router
    participant Handler as Tool Handler

    Client->>Transport: {"jsonrpc":"2.0","id":1,"method":"initialize"}
    Transport->>Router: parse + validate
    Router-->>Transport: capabilities response
    Transport-->>Client: {"jsonrpc":"2.0","id":1,"result":{...}}

    Client->>Transport: {"method":"tools/call","params":{"name":"add","arguments":{"a":2,"b":3}}}
    Transport->>Router: parse
    Router->>Handler: dispatch(add, {a:2, b:3})
    Handler-->>Router: "5"
    Router-->>Transport: ToolResult
    Transport-->>Client: {"result":{"content":[{"type":"text","text":"5"}]}}

API Reference

Server(name, version)

Create a new MCP server.

@server.tool(name=None, description=None)

Register a function as a tool. Name defaults to the function name, description defaults to the docstring.

@server.resource(uri, name=None, description=None, mime_type="text/plain")

Register a function as a resource. The function is called when the client reads the resource URI.

ToolResult.text(str) / ToolResult.error(str) / ToolResult.json(data)

Factory methods for creating tool results.

server.run()

Start the server on stdio transport.

Running Tests

pip install -e ".[dev]"
pytest tests/ -v

License

MIT