Tutorials
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.
This page is a guide, not the original text.
What problem it solves
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.
Verified on 2026-11-16 (Asia/Shanghai). The current stable version on PyPI is mcp 2.3.0, matching the latest GitHub Release 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/.
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 page, checked on 2026-11-16. The official recommendation is:
uv add "mcp[cli]"You can also use:
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.
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.
- In an empty directory, create
server.pyusing the official example:
from mcp.server import MCPServer
mcp = MCPServer("Demo")
@mcp.tool()
def add(a: int, b: int) -> int:
"""Add two numbers."""
return a + b- Install the SDK with the
cliextra as in the previous section, then start the Inspector:
uv run mcp dev server.py- Expected effect (from the official README, not from a run on this machine): calling
addin the Inspector witha=1andb=2is documented to return3. Run it yourself and check. Do not treat that sentence as a verified local result. - 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.pyor commit them. For automated tests, official docs show an in-processClient(mcp)call, so you do not have to open a port first.
Common pitfalls
- Copying a v1 tutorial that still uses
FastMCPormcp.server.fastmcp. v2 renamed that class. A common error isModuleNotFoundError: No module named 'mcp.server.fastmcp'. Read the migration guide 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. 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 repository is licensed under MIT. This page is a paraphrase, for CQBase — Context & Query Base, of the README, Get started, What's new in v2, the Migration Guide, PyPI mcp 2.3.0, and the v2.3.0 release notes, all checked on 2026-11-16. If install commands or class names change, the official docs and PyPI win.
In this category
- Tutorials
Generative AI for Beginners
Microsoft’s beginner course: lessons that connect prompting, apps, and retrieval.
microsoft - Tutorials
AI Agents for Beginners
Microsoft’s 18-lesson course, from chat to tool calls and multi-step tasks.
microsoft - Tutorials
Claude Cookbooks
Anthropic’s notebooks of concrete Claude recipes, closer to runnable code than a product page.
anthropics