/ Directory / Playground / MCP Python SDK
← All servers ↗ GitHub
● Official modelcontextprotocol ⚡ Instant

MCP Python SDK

by modelcontextprotocol · modelcontextprotocol/python-sdk

Official Python SDK for the Model Context Protocol — build servers and clients in 30 lines, ships with FastMCP-compatible decorators.

The official Anthropic-maintained Python SDK for MCP. Provides server (mcp.server.fastmcp.FastMCP), client (mcp.client.session.ClientSession), and lower-level primitives. Used as the canonical reference for spec compliance — when in doubt, this is the source of truth. The decorator-based FastMCP API has been merged in from jlowin/fastmcp.

▶ Watch demo 📦 Install 💡 Use Cases

Why use it

Key features

Live Demo

What it looks like in practice

mcp-python-sdk.replay ▶ ready
0/0

Install

Pick your client

~/Library/Application Support/Claude/claude_desktop_config.json  · Windows: %APPDATA%\Claude\claude_desktop_config.json
{
  "mcpServers": {
    "mcp-python-sdk": {
      "command": "uvx",
      "args": [
        "--with",
        "mcp",
        "python",
        "-m",
        "mcp.server.example"
      ],
      "_inferred": true
    }
  }
}

Open Claude Desktop → Settings → Developer → Edit Config. Restart after saving.

~/.cursor/mcp.json · .cursor/mcp.json
{
  "mcpServers": {
    "mcp-python-sdk": {
      "command": "uvx",
      "args": [
        "--with",
        "mcp",
        "python",
        "-m",
        "mcp.server.example"
      ],
      "_inferred": true
    }
  }
}

Cursor uses the same mcpServers schema as Claude Desktop. Project config wins over global.

VS Code → Cline → MCP Servers → Edit
{
  "mcpServers": {
    "mcp-python-sdk": {
      "command": "uvx",
      "args": [
        "--with",
        "mcp",
        "python",
        "-m",
        "mcp.server.example"
      ],
      "_inferred": true
    }
  }
}

Click the MCP Servers icon in the Cline sidebar, then "Edit Configuration".

~/.codeium/windsurf/mcp_config.json
{
  "mcpServers": {
    "mcp-python-sdk": {
      "command": "uvx",
      "args": [
        "--with",
        "mcp",
        "python",
        "-m",
        "mcp.server.example"
      ],
      "_inferred": true
    }
  }
}

Same shape as Claude Desktop. Restart Windsurf to pick up changes.

~/.continue/config.json
{
  "mcpServers": [
    {
      "name": "mcp-python-sdk",
      "command": "uvx",
      "args": [
        "--with",
        "mcp",
        "python",
        "-m",
        "mcp.server.example"
      ]
    }
  ]
}

Continue uses an array of server objects rather than a map.

~/.config/zed/settings.json
{
  "context_servers": {
    "mcp-python-sdk": {
      "command": {
        "path": "uvx",
        "args": [
          "--with",
          "mcp",
          "python",
          "-m",
          "mcp.server.example"
        ]
      }
    }
  }
}

Add to context_servers. Zed hot-reloads on save.

claude mcp add mcp-python-sdk -- uvx --with mcp python -m mcp.server.example

One-liner. Verify with claude mcp list. Remove with claude mcp remove.

Use Cases

Real-world ways to use MCP Python SDK

Build your first MCP server in Python in under 10 minutes

👤 Python devs new to MCP ⏱ ~15 min beginner

When to use: You want to expose a Python function to Claude.

Prerequisites
  • Python 3.10+ — uv or pyenv
Flow
  1. Install and scaffold
    Use uv to install mcp. Create server.py with one tool: get_weather(city) that calls a public API.✓ Copied
    → 10-line file with @tool decorator
  2. Run via stdio
    Run mcp dev server.py. Open the MCP Inspector and verify the tool listing.✓ Copied
    → Tool callable from inspector
  3. Add to Claude Desktop
    Add to claude_desktop_config.json. Test from Claude.✓ Copied
    → Live response in chat

Outcome: Working MCP server in Python registered with Claude.

Pitfalls
  • Using print() in handler breaks stdio — Use logging to stderr; never write to stdout

Write integration tests for an MCP server using the SDK's client

👤 Devs publishing MCPs to production ⏱ ~30 min intermediate

When to use: You need CI tests that prove your MCP behaves correctly.

Flow
  1. Spawn the server
    Use mcp.client.stdio to spawn server.py and call list_tools(). Assert expected names.✓ Copied
    → Test passes
  2. Call each tool
    For each tool, call with a representative input and assert the output schema.✓ Copied
    → All tools verified
  3. Wire into pytest
    Convert into pytest fixtures so CI runs them on every PR.✓ Copied
    → Reusable test harness

Outcome: MCP server with confidence that tools won't regress.

Stream long-running tool output back to Claude as it happens

👤 Devs building MCPs for builds, deploys, or long simulations ⏱ ~45 min advanced

When to use: Tool takes minutes and you want progress in the chat, not after it's done.

Flow
  1. Use streamable HTTP transport
    Switch from stdio to streamable HTTP. Yield progress events from the tool.✓ Copied
    → Claude shows partial output during execution
  2. Add cancellation
    Honor cancel requests so user can abort if the tool takes too long.✓ Copied
    → Cancel works mid-run

Outcome: Tools that feel real-time even when slow.

Combinations

Pair with other MCPs for X10 leverage

mcp-python-sdk + mcp-go-mark3labs

Polyglot — perf-critical in Go, ML/data in Python

Use mcp-python-sdk for the model-serving MCP, mcp-go for the high-throughput one.✓ Copied
mcp-python-sdk + mcp-registry

Publish your Python MCP to the official registry

Submit metadata to modelcontextprotocol/registry once your server passes its tests.✓ Copied

Tools

What this MCP exposes

ToolInputsWhen to callCost
FastMCP name, version? Top-level server creation 0
@server.tool decorator on async function Each function you want exposed 0
@server.resource decorator with uri pattern Read-only data exposure 0
@server.prompt decorator on prompt builder Reusable prompt templates 0
ClientSession transport Testing or building MCP clients 0
stdio_server () Local mode 0

Cost & Limits

What this costs to run

API quota
N/A — library
Tokens per call
N/A
Monetary
Free (MIT)
Tip
Pin SDK version in pyproject.toml; spec evolves

Security

Permissions, secrets, blast radius

Credential storage: Whatever your tools need
Data egress: Controlled by your handlers

Troubleshooting

Common errors and fixes

Tool not appearing

Make sure the @tool decorator is on an async function and the function is registered before the server starts

Verify: Run `mcp dev server.py` and open the inspector
Pydantic validation errors

Tool inputs are validated by Pydantic; check type hints match what Claude is sending

Server hangs on stdin EOF

Make sure your async handlers don't deadlock — use anyio for compatibility

Alternatives

MCP Python SDK vs others

AlternativeWhen to use it insteadTradeoff
FastMCP (PrefectHQ)You want the original third-party fork with extra utilitiesNow mostly merged back; thin wrapper
mcp-go (mark3labs)Go is your languageDifferent ecosystem

More

Resources

📖 Read the official README on GitHub

🐙 Browse open issues

🔍 Browse all 400+ MCP servers and Skills