# MCP Python SDK

Canonical: https://cqbase.net/en/entry/mcp-python-sdk
Chinese: https://cqbase.net/zh/entry/mcp-python-sdk
English: https://cqbase.net/en/entry/mcp-python-sdk

> The official Python SDK for writing MCP servers and clients.

modelcontextprotocol/python-sdk is the official Python SDK, MIT licensed, with docs at py.sdk.modelcontextprotocol.io. Start here when you want to write a small server rather than only install someone else’s.

Run the minimal server from the docs until your client lists its tools, then add your own function. Read secrets from the environment. Do not commit them. Check the protocol version and the SDK version together.

## What problem it solves

[modelcontextprotocol/python-sdk](https://github.com/modelcontextprotocol/python-sdk) is the official Python SDK for the Model Context Protocol. Use it to write MCP servers and clients, not only to install a server someone else already built. A server can expose tools, resources, and prompts to an MCP-compatible host; the same package can also act as a client and speak transports such as stdio, Streamable HTTP, and SSE. The repository is MIT licensed and is not archived. The documentation site is [py.sdk.modelcontextprotocol.io](https://py.sdk.modelcontextprotocol.io/).

Verified on 2026-11-16 (Asia/Shanghai). The current stable version on PyPI is [mcp 2.3.0](https://pypi.org/project/mcp/), matching the latest GitHub Release [v2.3.0](https://github.com/modelcontextprotocol/python-sdk/releases/tag/v2.3.0). That release was published at 22:02 UTC on 2 October 2026, which is 06:02 Asia/Shanghai on 3 October 2026. The repository has been pushed since then; the most recent push was at 13:38 UTC on 5 November 2026, which is 21:38 Asia/Shanghai the same day, so there may be commits after the tagged release. Official docs say that `pip install mcp` now installs 2.x. v2 renames the high-level server class from `FastMCP` to `MCPServer` and speaks the 2026-07-28 protocol revision. v1.x remains on a maintenance line, with critical fixes and security patches, and its docs live at [/v1/](https://py.sdk.modelcontextprotocol.io/v1/).

## Who it is for

It is for Python developers who need to write a small MCP server, or a client that connects to an existing server. If you only want to attach an already published server in Claude Code, Cursor, or another host, start from that server’s own install docs; you do not need to begin with this SDK.

Official sources do not fully agree on the minimum Python version. The GitHub README checked on 2026-11-16 says “Python 3.11+.” The same day’s PyPI metadata has `requires_python = ">=3.10"`, the classifiers include 3.10 through 3.14, and the PyPI description says “Python 3.10+.” This guide did not run the package on 3.10. Before you install, check both the README and the PyPI metadata for the version you are about to install. If you only want less uncertainty, start with 3.11 or later.

## How to install it

The commands below come from the repository README and the [Get started](https://py.sdk.modelcontextprotocol.io/get-started/) page, checked on 2026-11-16. The official recommendation is:

```bash
uv add "mcp[cli]"
```

You can also use:

```bash
pip install "mcp[cli]"
```

The `cli` extra adds commands such as `mcp dev`, `mcp run`, and `mcp install`. If you do not need the command-line tools, you can install plain `mcp`. For one-off commands, `uv run --with "mcp[cli]" mcp ...` works without creating a project first.

If you maintain a library that is not ready to move to v2, the official migration guide suggests an upper bound such as `mcp>=1.28,<2`, so an unconstrained install does not jump to 2.x. When you do migrate from v1, the first change most projects hit is the import path: `from mcp.server.fastmcp import FastMCP` becomes `from mcp.server import MCPServer` in v2. The full mapping is in the [Migration Guide](https://py.sdk.modelcontextprotocol.io/migration/).

## A worked example

This path follows the minimal server in the official README, as a check that the install works. This guide did not run it, so it does not treat the documented return value as a result measured on this machine.

1. In an empty directory, create `server.py` using the official example:

```python
from mcp.server import MCPServer

mcp = MCPServer("Demo")

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

2. Install the SDK with the `cli` extra as in the previous section, then start the Inspector:

```bash
uv run mcp dev server.py
```

3. Expected effect (from the official README, not from a run on this machine): calling `add` in the Inspector with `a=1` and `b=2` is documented to return `3`. Run it yourself and check. Do not treat that sentence as a verified local result.
4. After the Inspector lists the tool, connect the same server to the host you actually use and confirm that the host sees the same tools. Read secrets and other sensitive settings from the environment; do not put them in `server.py` or commit them. For automated tests, official docs show an in-process `Client(mcp)` call, so you do not have to open a port first.

## Common pitfalls

- Copying a v1 tutorial that still uses `FastMCP` or `mcp.server.fastmcp`. v2 renamed that class. A common error is `ModuleNotFoundError: No module named 'mcp.server.fastmcp'`. Read the [migration guide](https://py.sdk.modelcontextprotocol.io/migration/) first.
- Reading only the GitHub README or only PyPI, and missing the disagreement about the minimum Python version. Check both, then verify on your own machine.
- Leaving a dependency unpinned and resolving to 2.x before you are ready to migrate. Official docs suggest a temporary bound such as `mcp>=1.28,<2`.
- Writing API keys or internal URLs into server code. Use environment variables.
- Treating “latest release 2.3.0” as identical to every line on the repository’s default branch. 2.3.0 was published on 3 October 2026, and the repository was still pushed on 5 November 2026. If you need an exact commit, compare the tag with `main`; do not describe unreleased changes as already released.
- Choosing the wrong transport. Local debugging often uses stdio or `mcp dev`; official deploy examples use Streamable HTTP. Confirm the tool list in the Inspector before you attach a host.

## FAQ

### Which version should I install now?

As of 2026-11-16, the latest official version on both PyPI and GitHub Releases is 2.3.0 (06:02 Asia/Shanghai on 3 October 2026). Official docs say `pip install mcp` installs 2.x. The repository has been pushed since that release; if you need a frozen dependency, pin the version number explicitly.

### What is the minimum Python version?

The GitHub README says 3.11+. PyPI metadata has `requires_python = ">=3.10"`, and the PyPI description also says 3.10+. Those statements are not the same. This guide did not run the package on 3.10. Follow the metadata for the version you install, or start with 3.11 or later.

### Can I still use `FastMCP`?

In v2, the high-level server class is named `MCPServer`. Official migration notes say the old `mcp.server.fastmcp` import path was removed rather than kept as a compatibility alias. New code should use `from mcp.server import MCPServer`. If you are not migrating yet, stay on the v1.x maintenance line.

### Can I keep using v1?

Yes. Official docs say v1.x continues to receive critical fixes and security patches, with documentation at `/v1/`. If a library you publish still depends on v1, add an upper bound such as `<2`, so users do not install 2.x from an unconstrained resolve.

### What is the license, and how do I confirm that a tool actually registered?

The repository and PyPI both declare the MIT License; see [LICENSE](https://github.com/modelcontextprotocol/python-sdk/blob/main/LICENSE). To confirm registration, list and call the tool in the MCP Inspector, or in the in-process `Client` test shown in official docs, before you attach a host. This guide did not run those steps and does not invent Inspector output.

## Sources and license

The [modelcontextprotocol/python-sdk](https://github.com/modelcontextprotocol/python-sdk) repository is licensed under MIT. This page is a paraphrase, for CQBase — Context & Query Base, of the README, [Get started](https://py.sdk.modelcontextprotocol.io/get-started/), [What's new in v2](https://py.sdk.modelcontextprotocol.io/whats-new/), the [Migration Guide](https://py.sdk.modelcontextprotocol.io/migration/), [PyPI mcp 2.3.0](https://pypi.org/project/mcp/), and the [v2.3.0 release notes](https://github.com/modelcontextprotocol/python-sdk/releases/tag/v2.3.0), all checked on 2026-11-16. If install commands or class names change, the official docs and PyPI win.

## Catalog record

- Author: modelcontextprotocol
- License: MIT
- Source: https://github.com/modelcontextprotocol/python-sdk
- Added: 2026-11-15
- GitHub stars: 24868 (captured 2026-11-15)

