|
1 | 1 | # MCP Python SDK |
2 | 2 |
|
3 | | -<div align="center"> |
| 3 | +Fork of the official Python SDK for Model Context Protocol servers and clients. |
4 | 4 |
|
5 | | -<strong>Python implementation of the Model Context Protocol (MCP)</strong> |
| 5 | +## Purpose |
| 6 | +Working with and extending the Python implementation of the MCP SDK for local agent development and tool integration. |
6 | 7 |
|
7 | | -[![PyPI][pypi-badge]][pypi-url] |
8 | | -[![MIT licensed][mit-badge]][mit-url] |
9 | | -[![Python Version][python-badge]][python-url] |
10 | | -[![Documentation][docs-badge]][docs-url] |
11 | | -[![Protocol][protocol-badge]][protocol-url] |
12 | | -[![Specification][spec-badge]][spec-url] |
| 8 | +## Status |
| 9 | +Experimental / exploratory usage. |
13 | 10 |
|
14 | | -</div> |
15 | | - |
16 | | -> [!CAUTION] |
17 | | -> **This README documents v2 of the MCP Python SDK — a pre-release (alpha/beta) line under active development. Do not use v2 in production.** Pre-releases are published to PyPI as `2.0.0aN` / `2.0.0bN`, and **each pre-release may contain breaking changes from the previous one**. Pin an exact version and expect to update your code when you bump the pin. |
18 | | -> |
19 | | -> **v1.x is the only stable release line and remains recommended for production.** It lives on the [`v1.x` branch](https://github.com/modelcontextprotocol/python-sdk/tree/v1.x) and continues to receive critical bug fixes and security patches; see [the v1.x README](https://github.com/modelcontextprotocol/python-sdk/blob/v1.x/README.md) for its documentation. `pip` and `uv` don't select a pre-release unless you explicitly request one, so existing installs are unaffected. **If your package depends on `mcp`, add a `<2` upper bound to your version constraint (for example `mcp>=1.27,<2`) before the stable release lands.** |
20 | | -> |
21 | | -> v2 is a major rework of the SDK, both to support the [2026-07-28 MCP specification release](https://blog.modelcontextprotocol.io/posts/2026-07-28-release-candidate/) and to fix long-standing architectural issues. See [What's new in v2](https://py.sdk.modelcontextprotocol.io/v2/whats-new/) for the tour of what changed, and the [migration guide](https://py.sdk.modelcontextprotocol.io/v2/migration/) for every breaking change. Stable v2 is targeted for 2026-07-27, alongside the spec release. Try the pre-releases and [tell us what breaks](https://github.com/modelcontextprotocol/python-sdk/issues/new?template=v2-feedback.yaml), or discuss in [#python-sdk-dev on the MCP Contributors Discord](https://discord.gg/6CSzBmMkjX). |
22 | | -
|
23 | | -## Documentation |
24 | | - |
25 | | -**The documentation lives at <https://py.sdk.modelcontextprotocol.io/v2/>.** |
26 | | - |
27 | | -It has a [Get started guide](https://py.sdk.modelcontextprotocol.io/v2/get-started/), [What's new in v2](https://py.sdk.modelcontextprotocol.io/v2/whats-new/), the [API reference](https://py.sdk.modelcontextprotocol.io/v2/api/mcp/), and the [migration guide](https://py.sdk.modelcontextprotocol.io/v2/migration/). |
28 | | - |
29 | | -## What is MCP? |
30 | | - |
31 | | -The [Model Context Protocol](https://modelcontextprotocol.io) 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: |
32 | | - |
33 | | -- **Build MCP servers** that expose tools, resources, and prompts to any MCP host |
34 | | -- **Build MCP clients** that connect to any MCP server |
35 | | -- Speak every standard transport: stdio, Streamable HTTP, and SSE |
36 | | - |
37 | | -## Requirements |
38 | | - |
39 | | -Python 3.10+. |
40 | | - |
41 | | -## Installation |
42 | | - |
43 | | -```bash |
44 | | -uv add "mcp[cli]==2.0.0b1" # or: pip install "mcp[cli]==2.0.0b1" |
45 | | -``` |
46 | | - |
47 | | -The pin matters while v2 is in pre-release: an unpinned install resolves to the latest stable v1.x, which this README does not describe. Check [PyPI](https://pypi.org/project/mcp/#history) for the newest pre-release, and use `uv run --with "mcp==2.0.0b1"` for one-off commands. |
48 | | - |
49 | | -## A server in 15 lines |
50 | | - |
51 | | -Create a `server.py`: |
52 | | - |
53 | | -<!-- snippet-source docs_src/index/tutorial001.py --> |
54 | | -```python |
55 | | -from mcp.server import MCPServer |
56 | | - |
57 | | -mcp = MCPServer("Demo") |
58 | | - |
59 | | - |
60 | | -@mcp.tool() |
61 | | -def add(a: int, b: int) -> int: |
62 | | - """Add two numbers.""" |
63 | | - return a + b |
64 | | - |
65 | | - |
66 | | -@mcp.resource("greeting://{name}") |
67 | | -def greeting(name: str) -> str: |
68 | | - """Greet someone by name.""" |
69 | | - return f"Hello, {name}!" |
70 | | -``` |
71 | | - |
72 | | -_Full example: [docs_src/index/tutorial001.py](https://github.com/modelcontextprotocol/python-sdk/blob/main/docs_src/index/tutorial001.py)_ |
73 | | -<!-- /snippet-source --> |
74 | | - |
75 | | -That's a complete MCP server: one tool, one templated resource. Open it in the [MCP Inspector](https://github.com/modelcontextprotocol/inspector): |
76 | | - |
77 | | -```bash |
78 | | -uv run mcp dev server.py |
79 | | -``` |
80 | | - |
81 | | -Call `add` with `a=1`, `b=2` and you get `3` back. |
82 | | - |
83 | | -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. |
84 | | - |
85 | | -[Get started](https://py.sdk.modelcontextprotocol.io/v2/get-started/) takes it from here. |
86 | | - |
87 | | -## A client in 10 lines |
88 | | - |
89 | | -The same package is a full MCP **client**. `Client` connects to a URL, a stdio subprocess, a custom transport, or (for tests) straight to a server object in memory with no transport at all: |
90 | | - |
91 | | -```python |
92 | | -import asyncio |
93 | | - |
94 | | -from mcp import Client |
95 | | - |
96 | | -from server import mcp |
97 | | - |
98 | | - |
99 | | -async def main() -> None: |
100 | | - async with Client(mcp) as client: |
101 | | - result = await client.call_tool("add", {"a": 1, "b": 2}) |
102 | | - print(result.structured_content) # {'result': 3} |
103 | | - |
104 | | - |
105 | | -asyncio.run(main()) |
106 | | -``` |
107 | | - |
108 | | -Swap `mcp` for `"http://localhost:8000/mcp"` and the exact same code talks to a remote server. |
109 | | - |
110 | | -## Contributing |
111 | | - |
112 | | -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](https://github.com/modelcontextprotocol/python-sdk/blob/main/CONTRIBUTING.md) to get started. |
113 | | - |
114 | | -## License |
115 | | - |
116 | | -This project is licensed under the MIT License. See the [LICENSE](https://github.com/modelcontextprotocol/python-sdk/blob/main/LICENSE) file for details. |
117 | | - |
118 | | -[pypi-badge]: https://img.shields.io/pypi/v/mcp.svg |
119 | | -[pypi-url]: https://pypi.org/project/mcp/ |
120 | | -[mit-badge]: https://img.shields.io/pypi/l/mcp.svg |
121 | | -[mit-url]: https://github.com/modelcontextprotocol/python-sdk/blob/main/LICENSE |
122 | | -[python-badge]: https://img.shields.io/pypi/pyversions/mcp.svg |
123 | | -[python-url]: https://www.python.org/downloads/ |
124 | | -[docs-badge]: https://img.shields.io/badge/docs-python--sdk-blue.svg |
125 | | -[docs-url]: https://py.sdk.modelcontextprotocol.io/v2/ |
126 | | -[protocol-badge]: https://img.shields.io/badge/protocol-modelcontextprotocol.io-blue.svg |
127 | | -[protocol-url]: https://modelcontextprotocol.io |
128 | | -[spec-badge]: https://img.shields.io/badge/spec-spec.modelcontextprotocol.io-blue.svg |
129 | | -[spec-url]: https://modelcontextprotocol.io/specification/latest |
| 11 | +Original repository: [modelcontextprotocol/python-sdk](https://github.com/modelcontextprotocol/python-sdk) |
0 commit comments