python-sdk README

The project's README from github.com/modelcontextprotocol/python-sdk. As one markdown file: README.md.

MCP Python SDK

Python implementation of the Model Context Protocol (MCP)

PyPI MIT licensed Python Version Documentation Protocol Specification

[!NOTE] This is v2 of the MCP Python SDK, the current stable release line. It is a major rework of the SDK, both to support the 2026-07-28 MCP specification (and every earlier revision) and to fix long-standing architectural issues. Coming from v1? See What's new in v2 for the tour of what changed and the migration guide for every breaking change.

Not ready to migrate? v1.x lives on the v1.x branch, continues to receive critical bug fixes and security patches, and is documented at https://py.sdk.modelcontextprotocol.io/v1/. Since pip install mcp now installs 2.x, keep a <2 upper bound on your requirement (for example mcp>=1.28,<2) until you've migrated.

Something rough, confusing, or broken? Open an issue or find us in #python-sdk-dev on the MCP Contributors Discord.

Documentation

The documentation lives at https://py.sdk.modelcontextprotocol.io/.

It has a Get started guide, What's new in v2, the API reference, and the migration guide.

What is MCP?

The Model Context Protocol lets you build servers that expose data and functionality to LLM applications in a secure, standardized way. Think of it like a web API, but designed for LLM interactions. With this SDK you can:

Requirements

Python 3.10+.

Installation

uv add "mcp[cli]"      # or: pip install "mcp[cli]"

The cli extra adds the mcp command-line tool (mcp dev, mcp run, mcp install) on top of the SDK; install plain mcp if you don't need it. For one-off commands, uv run --with "mcp[cli]" mcp ... works without a project.

A server in 15 lines

Create a server.py:

from mcp.server import MCPServer

mcp = MCPServer("Demo")


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


@mcp.resource("greeting://{name}")
def greeting(name: str) -> str:
    """Greet someone by name."""
    return f"Hello, {name}!"

Full example: docs_src/index/tutorial001.py

That's a complete MCP server: one tool, one templated resource. Open it in the MCP Inspector:

uv run mcp dev server.py

Call add with a=1, b=2 and you get 3 back.

Notice what you did not write: no JSON Schema (a: int, b: int is the schema), no request parsing, no validation code, no protocol handling. Two type-hinted Python functions and a docstring.

Get started takes it from here.

A client in 10 lines

The same package is a full MCP client. Serve server.py over HTTP:

uv run mcp run server.py --transport streamable-http

then point a Client at it:

import asyncio

from mcp import Client


async def main() -> None:
    async with Client("http://localhost:8000/mcp") as client:
        result = await client.call_tool("add", {"a": 1, "b": 2})
        print(result.structured_content)  # {'result': 3}


asyncio.run(main())

A URL means Streamable HTTP, the transport you deploy. Client can also launch a local server as a stdio subprocess or take any custom transport; Clients has the rest.

Contributing

We are passionate about supporting contributors of all levels of experience and would love to see you get involved in the project. See the contributing guide to get started.

License

This project is licensed under the MIT License. See the LICENSE file for details.

python-sdk (modelcontextprotocol/python-sdk)

Searching Database…

24.6K ·GitHub
Python-sdk
What is this?The official Python SDK for the Model Context Protocol (MCP) — think a web API, but designed for LLM interactions. It lets you build servers that expose data and functionality to LLM applications, and clients that connect to any MCP server.
So is it a library I add to my own code, or a standalone tool?A pip-installable Python library (the package is called mcp), not a standalone app — you import it into your server or client code. An optional cli extra adds an mcp command-line tool on top for dev workflows.
How do I get a first server running?pip install 'mcp[cli]', create a server.py with decorated, type-hinted Python functions, and run it — the tutorial's complete server (one tool, one templated resource) is just 15 lines.
Which Python version do I need?Just Python 3.10 or newer. The package ships on PyPI, so a normal pip or uv install covers the rest.
I already built on v1 — do I have to rewrite everything for v2?v2 is a major rework with breaking changes, and the docs include a migration guide for every one of them. If you're not ready, v1.x lives on its own branch and still receives critical bug fixes and security patches.
What can a server expose to an LLM app?Tools, resources (including templated ones), and prompts — consumable by any MCP host. The tutorial example defines one tool and one templated resource.
How do I poke at my server while developing it?mcp dev opens it in the MCP Inspector — in the tutorial, calling add with a=1, b=2 returns 3, with no client code written.
Can I run it for one-off commands without setting up a project?Yes — uv run --with 'mcp[cli]' mcp ... works without a project.
Which MCP spec versions does the v2 SDK support?The 2026-07-28 specification and every earlier revision. v2 was reworked around it while also fixing long-standing architectural issues.
What are similar projects?fastmcp, typescript-sdk, TetreesAgent_EX, executor, mcp-for-beginners, mcp-use, Baize, gitagent
Which topics is it in?mcp-client, protocol, model-context-protocol, sdk, mcp-server, mcp, api, llm, library, ai, cli, python
Creator
modelcontextprotocol
Size
17 MB
Stars
24.6K
Updated
CommitOct 16Releasev2.3.0Oct 02
Age
2y
Commits · 90 Days