{"repo":"modelcontextprotocol/python-sdk","free":true,"listed":false,"github":"https://github.com/modelcontextprotocol/python-sdk","clone":"git clone https://github.com/modelcontextprotocol/python-sdk.git","description":"The official Python SDK for Model Context Protocol servers and clients","language":"Python","stars":24022,"topics":["mcp","mcp-client","mcp-server","python"],"license":"MIT","category":"llm_agent_framework","readme_excerpt":"# MCP Python SDK\n\n<div align=\"center\">\n\n<strong>Python implementation of the Model Context Protocol (MCP)</strong>\n\n[![PyPI][pypi-badge]][pypi-url]\n[![MIT licensed][mit-badge]][mit-url]\n[![Python Version][python-badge]][python-url]\n[![Documentation][docs-badge]][docs-url]\n[![Protocol][protocol-badge]][protocol-url]\n[![Specification][spec-badge]][spec-url]\n\n</div>\n\n> [!NOTE]\n> **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](https://modelcontextprotocol.io/specification/2026-07-28) (and every earlier revision) and to fix long-standing architectural issues. Coming from v1? See [What's new in v2](https://py.sdk.modelcontextprotocol.io/whats-new/) for the tour of what changed and the [migration guide](https://py.sdk.modelcontextprotocol.io/migration/) for every breaking change.\n>\n> **Not ready to migrate?** v1.x lives on the [`v1.x` branch](https://github.com/modelcontextprotocol/python-sdk/tree/v1.x), 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.\n>\n> Something rough, confusing, or broken? [Open an issue](https://github.com/modelcontextprotocol/python-sdk/issues/new?template=v2-feedback.yaml) or find us in [#python-sdk-dev on the MCP Contributors Discord](https://discord.gg/6CSzBmMkjX).\n\n## Documentation\n\n**The documentation lives at <https://py.sdk.modelcontextprotocol.io/>.**\n\nIt has a [Get started guide](https://py.sdk.modelcontextprotocol.io/get-started/), [What's new in v2](https://py.sdk.modelcontextprotocol.io/whats-new/), the [API reference](https://py.sdk.modelcontextprotocol.io/api/mcp/), and the [migration guide](https://py.sdk.modelcontextprotocol.io/migration/).\n\n## What is MCP?\n\nThe [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:\n\n- **Build MCP servers** that expose tools, resources, and prompts to any MCP host\n- **Build MCP clients** that connect to any MCP server\n- Speak every standard transport: stdio, Streamable HTTP, and SSE\n\n## Requirements\n\nPython 3.10+.\n\n## Installation\n\n```bash\nuv add \"mcp[cli]\"      # or: pip install \"mcp[cli]\"\n```\n\nThe `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.\n\n## A server in 15 lines\n\nCreate a `server.py`:\n\n<!-- snippet-source docs_src/index/tutorial001.py -->\n```python\nfrom mcp.server import MCPServer\n\nmcp = MCPServer(\"Demo\")\n\n\n@mcp.tool()\ndef add(a: int, b: int) -> int:\n    \"\"\"Add two numbers.\"\"\"\n    return a + b\n\n\n@mcp.resource(\"greeting://{name}\")\ndef greeting(name: str) -> str:\n    \"\"\"Greet someone by name.\"\"\"\n    return f\"Hello, {name}!\"\n```\n\n_Full example: [docs_src/index/tutorial001.py](https://github.com/modelcontextprotocol/python-sdk/blob/main/docs_src/index/tutorial001.py)_\n<!-- /snippet-source -->\n\nThat's a complete MCP server: one tool, one templated resource. Open it in the [MCP Inspector](https://github.com/modelcontextprotocol/inspector):\n\n```bash\nuv run mcp dev server.py\n```\n\nCall `add` with `a=1`, `b=2` and you get `3` back.\n\nNotice 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.\n\n[Get started](https://py.sdk.modelcontextprotocol.io/get-started/) takes it from here.\n\n## A client in 10 lines\n\nThe same package is a full MCP **client**. Serve `server.py` over HTTP:\n\n```bash\nuv run mcp run server.py --transport streamable-http\n```\n\nthen point a `Client` at it:\n\n```python\nimport asyncio\n\nfrom mcp import Client\n\n\nasync def main() -> None:\n    async with Client(\"http://localhost:8000/mcp\") as client:\n        result = await client.call_tool(\"add\", {\"a\": 1, \"b\": 2})\n        print(result.structured_content)  # {'result': 3}\n\n\nasyncio.run(main())\n```\n\nA 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](https://py.sdk.modelcontextprotocol.io/client/) has the rest.\n\n## Contributing\n\nWe 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.\n\n## License\n\nThis project is licensed under the MIT License. See the [LICENSE](https://github.com/modelcontextprotocol/python-sdk/blob/main/LICENSE) file for details.\n\n[pypi-badge]: https://img.shields.io/pypi/v/mcp.svg\n[pypi-url]: https://pypi.org/project/mcp/\n[mit-badge]: https://img.shields.io/pypi/l/mcp.svg\n[mit-url]: https://github.com/modelcontextprotocol/python-sdk/blob/main/LICENSE\n[python-badge]: https://img.shields.io/pypi/pyversions/mcp.svg\n[python-url]: https://www.python.org/downloads/\n[docs-badge]: https://img.shields.io/badge/docs-python--sdk-blue.svg\n[docs-url]: https://py.sdk.modelcontextprotocol.io/\n[protocol-badge]: https://img.shields.io/badge/protocol-modelcontextprotocol.io-blue.svg\n[protocol-url]: https://modelcontextprotocol.io\n[spec-badge]: https://img.shields.io/badge/spec-spec.modelcontextprotocol.io-blue.svg\n[spec-url]: https://modelcontextprotocol.io/specification/latest\n","default_branch":"main","files":1653,"tree":[".claude/commands/review-pr.md",".claude/skills/test-quality/SKILL.md",".git-blame-ignore-revs",".gitattributes",".github/ISSUE_TEMPLATE/bug.yaml",".github/ISSUE_TEMPLATE/config.yaml",".github/ISSUE_TEMPLATE/feature-request.yaml",".github/ISSUE_TEMPLATE/question.yaml",".github/ISSUE_TEMPLATE/v2-feedback.yaml",".github/actions/conformance/client.py",".github/actions/conformance/expected-failures.2025-11-25.yml",".github/actions/conformance/expected-failures.2026-07-28.yml",".github/actions/conformance/expected-failures.yml",".github/actions/conformance/run-client.sh",".github/actions/conformance/run-server.sh",".github/dependabot.yml",".github/workflows/claude.yml",".github/workflows/conformance.yml",".github/workflows/deploy-docs.yml",".github/workflows/docs-preview-cleanup.yml",".github/workflows/docs-preview.yml",".github/workflows/main.yml",".github/workflows/publish-pypi.yml",".github/workflows/shared.yml",".github/workflows/zizmor.yml",".gitignore",".pre-commit-config.yaml","AGENTS.md","CLAUDE.md","CODE_OF_CONDUCT.md","CONTRIBUTING.md","DEPENDENCY_POLICY.md","LICENSE","README.md","RELEASE.md","ROADMAP.md","SECURITY.md","VERSIONING.md","docs/.overrides/.icons/mcp.svg","docs/advanced/apps.md","docs/advanced/extensions.md","docs/advanced/index.md","docs/advanced/low-level-server.md","docs/advanced/middleware.md","docs/advanced/pagination.md","docs/client/caching.md","docs/client/callbacks.md","docs/client/identity-assertion.md","docs/client/index.md","docs/client/oauth-clients.md","docs/client/session-groups.md","docs/client/subscriptions.md","docs/client/transports.md","docs/deprecated.md","docs/extra.css","docs/favicon.svg","docs/get-started/first-steps.md","docs/get-started/index.md","docs/get-started/installation.md","docs/get-started/real-host.md","docs/get-started/testing.md","docs/handlers/context.md","docs/handlers/dependencies.md","docs/handlers/elicitation.md","docs/handlers/index.md","docs/handlers/lifespan.md","docs/handlers/logging.md","docs/handlers/multi-round-trip.md","docs/handlers/progress.md","docs/handlers/sampling-and-roots.md","docs/handlers/subscriptions.md","docs/index.md","docs/js/language-switch.js","docs/migration.md","docs/protocol-versions.md","docs/run/asgi.md","docs/run/authorization.md","docs/run/deploy.md","docs/run/index.md","docs/run/legacy-clients.md","docs/run/opentelemetry.md","docs/servers/completions.md","docs/servers/handling-errors.md","docs/servers/index.md","docs/servers/media.md","docs/servers/prompts.md","docs/servers/resources.md","docs/servers/structured-output.md","docs/servers/tools.md","docs/servers/uri-templates.md","docs/translations.md","docs/troubleshooting.md","docs/whats-new.md","docs_src/__init__.py","docs_src/apps/__init__.py","docs_src/apps/report.html","docs_src/apps/tutorial001.py","docs_src/apps/tutorial002.py","docs_src/apps/tutorial003.py","docs_src/asgi/__init__.py","docs_src/asgi/tutorial001.py","docs_src/asgi/tutorial002.py","docs_src/asgi/tutorial003.py","docs_src/asgi/tutorial004.py","docs_src/asgi/tutorial005.py","docs_src/asgi/tutorial006.py","docs_src/authorization/__init__.py","docs_src/authorization/tutorial001.py","docs_src/authorization/tutorial002.py","docs_src/caching/__init__.py","docs_src/caching/tutorial001.py","docs_src/caching/tutorial002.py","docs_src/caching/tutorial003.py","docs_src/client/__init__.py","docs_src/client/tutorial001.py","docs_src/client/tutorial002.py","docs_src/client/tutorial003.py","docs_src/client/tutorial004.py","docs_src/client/tutorial005.py","docs_src/client/tutorial006.py","docs_src/client/tutorial007.py","docs_src/client_callbacks/__init__.py","docs_src/client_callbacks/tutorial001.py","docs_src/client_callbacks/tutorial002.py","docs_src/client_callbacks/tutorial003.py","docs_src/client_callbacks/tutorial004.py","docs_src/client_transports/__init__.py","docs_src/client_transports/tutorial001.py","docs_src/client_transports/tutorial002.py","docs_src/client_transports/tutorial003.py","docs_src/client_transports/tutorial004.py","docs_src/completions/__init__.py","docs_src/completions/tutorial001.py","docs_src/completions/tutorial002.py","docs_src/completions/tutorial003.py","docs_src/context/__init__.py","docs_src/context/tutorial001.py","docs_src/context/tutorial002.py","docs_src/context/tutorial003.py","docs_src/dependencies/__init__.py","docs_src/dependencies/tutorial001.py","docs_src/dependencies/tutorial002.py","docs_src/dependencies/tutorial003.py","docs_src/dependencies/tutorial004.py","docs_src/deploy/__init__.py","docs_src/deploy/tutorial001.py","docs_src/deploy/tutorial002.py","docs_src/deploy/tutorial003.py","docs_src/deploy/tutorial004.py","docs_src/elicitation/__init__.py","docs_src/elicitation/tutorial001.py","docs_src/elicitation/tutorial002.py","docs_src/elicitation/tutorial003.py","docs_src/elicitation/tutorial004.py","docs_src/extensions/__init__.py","docs_src/extensions/tutorial001.py","docs_src/extensions/tutorial002.py","docs_src/extensions/tutorial003.py","docs_src/extensions/tutorial004.py","docs_src/extensions/tutorial005.py","docs_src/extensions/tutorial006.py","docs_src/extensions/tutorial007.py","docs_src/first_steps/__init__.py","docs_src/first_steps/tutorial001.py","docs_src/handling_errors/__init__.py","docs_src/handling_errors/tutorial001.py","docs_src/handling_errors/tutorial002.py","docs_src/handling_errors/tutorial003.py","docs_src/identity_assertion/__init__.py","docs_src/identity_assertion/tutorial001.py","docs_src/identity_assertion/tutorial002.py","docs_src/index/__init__.py","docs_src/index/tutorial001.py","docs_src/legacy_clients/__init__.py","docs_src/legacy_clients/tutorial001.py","docs_src/legacy_clients/tutorial002.py","docs_src/legacy_clients/tutorial003.py","docs_src/lifespan/__init__.py","docs_src/lifespan/tutorial001.py","docs_src/lifespan/tutorial002.py","docs_src/logging/__init__.py","docs_src/logging/tutorial001.py","docs_src/lowlevel/__init__.py","docs_src/lowlevel/tutorial001.py","docs_src/lowlevel/tutorial002.py","docs_src/lowlevel/tutorial003.py","docs_src/lowlevel/tutorial004.py","docs_src/lowlevel/tutorial005.py","docs_src/lowlevel/tutorial006.py","docs_src/media/__init__.py","docs_src/media/tutorial001.py","docs_src/media/tutorial002.py","docs_src/media/tutorial003.py","docs_src/media/tutorial004.py","docs_src/middleware/__init__.py","docs_src/middleware/tutorial001.py","docs_src/mrtr/__init__.py","docs_src/mrtr/tutorial001.py","docs_src/mrtr/tutorial002.py","docs_src/mrtr/tutorial003.py","docs_src/mrtr/tutorial004.py","docs_src/mrtr/tutorial005.py","docs_src/oauth_clients/__init__.py","docs_src/oauth_clients/tutorial001.py","docs_src/oauth_clients/tutorial002.py","docs_src/opentelemetry/__init__.py","docs_src/opentelemetry/tutorial001.py","docs_src/pagination/__init__.py","docs_src/pagination/tutorial001.py","docs_src/pagination/tutorial002.py","docs_src/progress/__init__.py","docs_src/progress/tutorial001.py","docs_src/progress/tutorial002.py","docs_src/prompts/__init__.py","docs_src/prompts/tutorial001.py","docs_src/prompts/tutorial002.py","docs_src/prompts/tutorial003.py","docs_src/protocol_versions/__init__.py","docs_src/protocol_versions/tutorial001.py","docs_src/protocol_versions/tutorial002.py","docs_src/protocol_versions/tutorial003.py","docs_src/protocol_versions/tutorial004.py","docs_src/real_host/__init__.py","docs_src/real_host/tutorial001.py","docs_src/resources/__init__.py","docs_src/resources/tutorial001.py","docs_src/resources/tutorial002.py","docs_src/resources/tutorial003.py","docs_src/run/__init__.py","docs_src/run/tutorial001.py","docs_src/run/tutorial002.py","docs_src/run/tutorial003.py","docs_src/sampling_and_roots/__init__.py","docs_src/sampling_and_roots/tutorial001.py","docs_src/sampling_and_roots/tutorial002.py","docs_src/session_groups/__init__.py","docs_src/session_groups/tutorial001.py","docs_src/session_groups/tutorial002.py","docs_src/session_groups/tutorial003.py","docs_src/session_groups/tutorial004.py","docs_src/structured_output/__init__.py","docs_src/structured_output/tutorial001.py","docs_src/structured_output/tutorial002.py","docs_src/structured_output/tutorial003.py","docs_src/structured_output/tutorial004.py","docs_src/structured_output/tutorial005.py","docs_src/structured_output/tutorial006.py","docs_src/structured_output/tutorial007.py","docs_src/structured_output/tutorial008.py","docs_src/structured_output/tutorial009.py","docs_src/subscriptions/__init__.py","docs_src/subscriptions/tutorial001.py","docs_src/subscriptions/tutorial002.py","docs_src/subscriptions/tutorial003.py","docs_src/subscriptions/tutorial004_anyio.py","docs_src/subscriptions/tutorial004_asyncio.py","docs_src/subscriptions/tutorial004_trio.py","docs_src/subscriptions/tutorial005.py","docs_src/subscriptions/tutorial006.py","docs_src/testing/__init__.py","docs_src/testing/tutorial001.py","docs_src/tools/__init__.py","docs_src/tools/tutorial001.py","docs_src/tools/tutorial002.py","docs_src/tools/tutorial003.py","docs_src/tools/tutorial004.py","docs_src/tools/tutorial005.py","docs_src/troubleshooting/__init__.py","docs_src/troubleshooting/tutorial001.py","docs_src/troubleshooting/tutorial002.py","docs_src/troubleshooting/tutorial003.py","docs_src/troubleshooting/tutorial004.py","docs_src/troubleshooting/tutorial005.py","docs_src/troubleshooting/tutorial006.py","docs_src/troubleshooting/tutorial007.py","docs_src/troubleshooting/tutorial008.py","docs_src/uri_templates/__init__.py","docs_src/uri_templates/tutorial001.py","docs_src/uri_templates/tutorial002.py","docs_src/uri_templates/tutorial003.py","docs_src/uri_templates/tutorial004.py","docs_src/uri_templates/tutorial005.py","docs_src/whats_new/__init__.py","docs_src/whats_new/tutorial001.py","examples/README.md","examples/clients/simple-auth-client/README.md","examples/clients/simple-auth-client/mcp_simple_auth_client/__init__.py","examples/clients/simple-auth-client/mcp_simple_auth_client/main.py","examples/clients/simple-auth-client/pyproject.toml","examples/clients/simple-chatbot/.python-version","examples/clients/simple-chatbot/README.MD","examples/clients/simple-chatbot/mcp_simple_chatbot/.env.example","examples/clients/simple-chatbot/mcp_simple_chatbot/main.py","examples/clients/simple-chatbot/mcp_simple_chatbot/requirements.txt","examples/clients/simple-chatbot/mcp_simple_chatbot/servers_config.json","examples/clients/simple-chatbot/mcp_simple_chatbot/test.db","examples/clients/simple-chatbot/pyproject.toml","examples/clients/sse-polling-client/README.md","examples/clients/sse-polling-client/mcp_sse_polling_client/__init__.py","examples/clients/sse-polling-client/mcp_sse_polling_client/main.py","examples/clients/sse-polling-client/pyproject.toml","examples/mcpserver/complex_inputs.py","examples/mcpserver/desktop.py","examples/mcpserver/direct_call_tool_result_return.py","examples/mcpserver/echo.py","examples/mcpserver/icons_demo.py","examples/mcpserver/logging_and_progress.py","examples/mcpserver/mcp.png","examples/mcpserver/memory.py","examples/mcpserver/parameter_descriptions.py","examples/mcpserver/readme-quickstart.py","examples/mcpserver/screenshot.py","examples/mcpserver/simple_echo.py","examples/mcpserver/text_me.py","examples/mcpserver/unicode_example.py","examples/mcpserver/weather_structured.py","examples/pyproject.toml","examples/servers/everything-server/README.md","examples/servers/everything-server/mcp_everything_server/__init__.py","examples/servers/everything-server/mcp_everything_server/__main__.py","examples/servers/everything-server/mcp_everything_server/server.py","examples/servers/everything-server/pyproject.toml","examples/servers/simple-auth/README.md","examples/servers/simple-auth/mcp_simple_auth/__init__.py","examples/servers/simple-auth/mcp_simple_auth/__main__.py","examples/servers/simple-auth/mcp_simple_auth/auth_server.py","examples/servers/simple-auth/mcp_simple_auth/legacy_as_server.py","examples/servers/simple-auth/mcp_simple_auth/py.typed","examples/servers/simple-auth/mcp_simple_auth/server.py","examples/servers/simple-auth/mcp_simple_auth/simple_auth_provider.py","examples/servers/simple-auth/mcp_simple_auth/token_verifier.py","examples/servers/simple-auth/pyproject.toml","examples/servers/simple-pagination/README.md","examples/servers/simple-pagination/mcp_simple_pagination/__init__.py","examples/servers/simple-pagination/mcp_simple_pagination/__main__.py","examples/servers/simple-pagination/mcp_simple_pagination/server.py","examples/servers/simple-pagination/pyproject.toml","examples/servers/simple-prompt/.python-version","examples/servers/simple-prompt/README.md","examples/servers/simple-prompt/mcp_simple_prompt/__init__.py","examples/servers/simple-prompt/mcp_simple_prompt/__main__.py","examples/servers/simple-prompt/mcp_simple_prompt/server.py","examples/servers/simple-prompt/pyproject.toml","examples/servers/simple-resource/.python-version","examples/servers/simple-resource/README.md","examples/servers/simple-resource/mcp_simple_resource/__init__.py","examples/servers/simple-resource/mcp_simple_resource/__main__.py","examples/servers/simple-resource/mcp_simple_resource/server.py","examples/servers/simple-resource/pyproject.toml","examples/servers/simple-streamablehttp-stateless/README.md","examples/servers/simple-streamablehttp-stateless/mcp_simple_streamablehttp_stateless/__init__.py","examples/servers/simple-streamablehttp-stateless/mcp_simple_streamablehttp_stateless/__main__.py","examples/servers/simple-streamablehttp-stateless/mcp_simple_streamablehttp_stateless/server.py","examples/servers/simple-streamablehttp-stateless/pyproject.toml","examples/servers/simple-streamablehttp/README.md","examples/servers/simple-streamablehttp/mcp_simple_streamablehttp/__init__.py","examples/servers/simple-streamablehttp/mcp_simple_streamablehttp/__main__.py","examples/servers/simple-streamablehttp/mcp_simple_streamablehttp/event_store.py","examples/servers/simple-streamablehttp/mcp_simple_streamablehttp/server.py","examples/servers/simple-streamablehttp/pyproject.toml","examples/servers/simple-tool/.python-version","examples/servers/simple-tool/README.md","examples/servers/simple-tool/mcp_simple_tool/__init__.py","examples/servers/simple-tool/mcp_simple_tool/__main__.py","examples/servers/simple-tool/mcp_simple_tool/server.py","examples/servers/simple-tool/pyproject.toml","examples/servers/sse-polling-demo/README.md","examples/servers/sse-polling-demo/mcp_sse_polling_demo/__init__.py","examples/servers/sse-polling-demo/mcp_sse_polling_demo/__main__.py","examples/servers/sse-polling-demo/mcp_sse_polling_demo/event_store.py","examples/servers/sse-polling-demo/mcp_sse_polling_demo/server.py","examples/servers/sse-polling-demo/pyproject.toml","examples/servers/structured-output-lowlevel/mcp_structured_output_lowlevel/__init__.py","examples/servers/structured-output-lowlevel/mcp_structured_output_lowlevel/__main__.py","examples/servers/structured-output-lowlevel/pyproject.toml","examples/snippets/clients/__init__.py","examples/snippets/clients/completion_client.py","examples/snippets/clients/display_utilities.py","examples/snippets/clients/identity_assertion_client.py","examples/snippets/clients/oauth_client.py","examples/snippets/clients/pagination_client.py","examples/snippets/clients/parsing_tool_results.py","examples/snippets/clients/stdio_client.py","examples/snippets/clients/streamable_basic.py","examples/snippets/clients/url_elicitation_client.py","examples/snippets/pyproject.toml","examples/snippets/servers/__init__.py","examples/snippets/servers/basic_prompt.py","examples/snippets/servers/basic_resource.py","examples/snippets/servers/basic_tool.py","examples/snippets/servers/completion.py","examples/snippets/servers/direct_call_tool_result.py","examples/snippets/servers/direct_execution.py","examples/snippets/servers/elicitation.py","examples/snippets/servers/identity_assertion_server.py","examples/snippets/servers/images.py","examples/snippets/servers/lifespan_example.py","examples/snippets/servers/lowlevel/__init__.py","examples/snippets/servers/lowlevel/basic.py","examples/snippets/servers/lowlevel/direct_call_tool_result.py"],"storefront":"/r/modelcontextprotocol","claimed":false,"request_supported":{"post":"https://gitbuyer.com/r/modelcontextprotocol/python-sdk/request-supported","requests":0},"note":"indexed from public GitHub; nothing is for sale on this page. Clone it from GitHub. Paid listings live at /search."}