{"id":22371553,"url":"https://github.com/jlowin/fastmcp","last_synced_at":"2025-05-13T20:02:40.361Z","repository":{"id":265588754,"uuid":"896296825","full_name":"jlowin/fastmcp","owner":"jlowin","description":"🚀 The fast, Pythonic way to build MCP servers and clients","archived":false,"fork":false,"pushed_at":"2025-05-06T17:46:05.000Z","size":1926,"stargazers_count":8848,"open_issues_count":41,"forks_count":469,"subscribers_count":44,"default_branch":"main","last_synced_at":"2025-05-06T19:52:09.861Z","etag":null,"topics":["fastmcp","llm","mcp","mcp-client","mcp-server","model-context-protocol"],"latest_commit_sha":null,"homepage":"https://gofastmcp.com","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/jlowin.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2024-11-30T01:47:40.000Z","updated_at":"2025-05-06T19:39:52.000Z","dependencies_parsed_at":"2024-11-30T03:17:49.088Z","dependency_job_id":"91d758be-1f23-4405-8ee6-e550c9dec0c7","html_url":"https://github.com/jlowin/fastmcp","commit_stats":null,"previous_names":["jlowin/fastmcp"],"tags_count":26,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jlowin%2Ffastmcp","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jlowin%2Ffastmcp/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jlowin%2Ffastmcp/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jlowin%2Ffastmcp/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/jlowin","download_url":"https://codeload.github.com/jlowin/fastmcp/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":253655723,"owners_count":21943066,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["fastmcp","llm","mcp","mcp-client","mcp-server","model-context-protocol"],"created_at":"2024-12-04T20:28:21.401Z","updated_at":"2025-05-13T20:02:40.346Z","avatar_url":"https://github.com/jlowin.png","language":"Python","funding_links":[],"categories":["Frameworks","MCP Servers \u0026 Tools","MCP Servers \u0026 Execution Sandboxes","Developer Tools","Python","MCP Server 开发","Development Tools Mcp Servers","MCP Frameworks and libraries","🔎 Select Context","Framework","Other Tools and Integrations","Agent Protocols","📚 Projects (1974 total)","🤝 Agent Frameworks \u0026 MCP","🤖 AI/ML","Building","Tools","MCP Ecosystem","Model Context Protocol (MCP)","模型上下文协议 MCP","Frameworks \u0026 Libraries","HarmonyOS","フレームワーク","Skills, Hooks, and MCP for Coordination","SDKs","Agent Communication \u0026 Protocols","Frameworks \u0026 Tools","框架","🙏 Acknowledgments","Tools and Code","Developer Tools \u0026 SDKs","Dev Tools (29)","Table of Contents","LLM Tools"],"sub_categories":["📋 Project Management","Infrastructure","MCP SDKs","**1. 使用 LLM 构建 MCP 服务器**","Python","MCP Frameworks","MCP Servers","Model Context Protocol (MCP) 🔥","🛠️ \u003ca name=\"other-tools-and-integrations\"\u003e\u003c/a\u003eOther Tools and Integrations","LLM Models","Community","Core \u0026 Frameworks","Knowledge Management","Windows Manager","📂 \u003ca name=\"browser-automation\"\u003e\u003c/a\u003eブラウザ自動化","🎧 \u003ca name=\"text-to-speech\"\u003e\u003c/a\u003eテキスト読み上げ","Multi-Agent Platforms","Example 2: Research a Topic","MCP (Model Context Protocol)","Developer Tools"],"readme":"\u003cdiv align=\"center\"\u003e\n\n\u003c!-- omit in toc --\u003e\n# FastMCP v2 🚀\n\u003cstrong\u003eThe fast, Pythonic way to build MCP servers and clients.\u003c/strong\u003e\n\n[![Docs](https://img.shields.io/badge/docs-gofastmcp.com-blue)](https://gofastmcp.com)\n[![PyPI - Version](https://img.shields.io/pypi/v/fastmcp.svg)](https://pypi.org/project/fastmcp)\n[![Tests](https://github.com/jlowin/fastmcp/actions/workflows/run-tests.yml/badge.svg)](https://github.com/jlowin/fastmcp/actions/workflows/run-tests.yml)\n[![License](https://img.shields.io/github/license/jlowin/fastmcp.svg)](https://github.com/jlowin/fastmcp/blob/main/LICENSE)\n\n\u003ca href=\"https://trendshift.io/repositories/13266\" target=\"_blank\"\u003e\u003cimg src=\"https://trendshift.io/api/badge/repositories/13266\" alt=\"jlowin%2Ffastmcp | Trendshift\" style=\"width: 250px; height: 55px;\" width=\"250\" height=\"55\"/\u003e\u003c/a\u003e\n\u003c/div\u003e\n\n\u003e [!NOTE]\n\u003e #### FastMCP 2.0 \u0026 The Official MCP SDK\n\u003e\n\u003e Recognize the `FastMCP` name? You might have seen the version that was contributed to the [official MCP Python SDK](https://github.com/modelcontextprotocol/python-sdk), which was based on **FastMCP 1.0**.\n\u003e\n\u003e **Welcome to FastMCP 2.0!** This is the actively developed successor, and it significantly expands on 1.0 by introducing powerful client capabilities, server proxying \u0026 composition, OpenAPI/FastAPI integration, and more advanced features.\n\u003e\n\u003e FastMCP 2.0 is the recommended path for building modern, powerful MCP applications. Ready to upgrade or get started? Follow the [installation instructions](https://gofastmcp.com/getting-started/installation), which include specific steps for upgrading from the official MCP SDK.\n\n---\n\nThe [Model Context Protocol (MCP)](https://modelcontextprotocol.io) is a new, standardized way to provide context and tools to your LLMs, and FastMCP makes building MCP servers and clients simple and intuitive. Create tools, expose resources, define prompts, and connect components with clean, Pythonic code.\n\n```python\n# server.py\nfrom fastmcp import FastMCP\n\nmcp = FastMCP(\"Demo 🚀\")\n\n@mcp.tool()\ndef add(a: int, b: int) -\u003e int:\n    \"\"\"Add two numbers\"\"\"\n    return a + b\n\nif __name__ == \"__main__\":\n    mcp.run()\n```\n\nRun the server locally:\n```bash\nfastmcp run server.py\n```\n\n### 📚 Documentation\n\nFastMCP's complete documentation is available at **[gofastmcp.com](https://gofastmcp.com)**, including detailed guides, API references, and advanced patterns. This readme provides only a high-level overview.\n\nDocumentation is also available in [llms.txt format](https://llmstxt.org/), which is a simple markdown standard that LLMs can consume easily. \n\nThere are two ways to access the LLM-friendly documentation:\n- [`llms.txt`](https://gofastmcp.com/llms.txt) is essentially a sitemap, listing all the pages in the documentation.\n- [`llms-full.txt`](https://gofastmcp.com/llms-full.txt) contains the entire documentation. Note this may exceed the context window of your LLM.\n\n---\n\n\u003c!-- omit in toc --\u003e\n## Table of Contents\n\n- [What is MCP?](#what-is-mcp)\n- [Why FastMCP?](#why-fastmcp)\n- [Installation](#installation)\n- [Core Concepts](#core-concepts)\n  - [The `FastMCP` Server](#the-fastmcp-server)\n  - [Tools](#tools)\n  - [Resources \\\u0026 Templates](#resources--templates)\n  - [Prompts](#prompts)\n  - [Context](#context)\n  - [MCP Clients](#mcp-clients)\n- [Advanced Features](#advanced-features)\n  - [Proxy Servers](#proxy-servers)\n  - [Composing MCP Servers](#composing-mcp-servers)\n  - [OpenAPI \\\u0026 FastAPI Generation](#openapi--fastapi-generation)\n- [Running Your Server](#running-your-server)\n- [Contributing](#contributing)\n  - [Prerequisites](#prerequisites)\n  - [Setup](#setup)\n  - [Unit Tests](#unit-tests)\n  - [Static Checks](#static-checks)\n  - [Pull Requests](#pull-requests)\n\n---\n\n## What is MCP?\n\nThe [Model Context Protocol (MCP)](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 specifically designed for LLM interactions. MCP servers can:\n\n- Expose data through **Resources** (similar to `GET` requests; load info into context)\n- Provide functionality through **Tools** (similar to `POST`/`PUT` requests; execute actions)\n- Define interaction patterns through **Prompts** (reusable templates)\n- And more!\n\nFastMCP provides a high-level, Pythonic interface for building and interacting with these servers.\n\n## Why FastMCP?\n\nThe MCP protocol is powerful but implementing it involves a lot of boilerplate - server setup, protocol handlers, content types, error management. FastMCP handles all the complex protocol details and server management, so you can focus on building great tools. It's designed to be high-level and Pythonic; in most cases, decorating a function is all you need.\n\nWhile the core server concepts of FastMCP 1.0 laid the groundwork and were contributed to the official MCP SDK, **FastMCP 2.0 (this project) is the actively developed successor**, adding significant enhancements and entirely new capabilities like a powerful **client library**, server **proxying**, **composition** patterns, **OpenAPI/FastAPI integration**, and much more.\n\nFastMCP aims to be:\n\n🚀 **Fast:** High-level interface means less code and faster development\n\n🍀 **Simple:** Build MCP servers with minimal boilerplate\n\n🐍 **Pythonic:** Feels natural to Python developers\n\n🔍 **Complete:** FastMCP aims to provide a full implementation of the core MCP specification for both servers and clients\n\n## Installation\n\nWe recommend installing FastMCP with [uv](https://docs.astral.sh/uv/):\n\n```bash\nuv pip install fastmcp\n```\n\nFor full installation instructions, including verification, upgrading from the official MCPSDK, and developer setup, see the [**Installation Guide**](https://gofastmcp.com/getting-started/installation).\n\n## Core Concepts\n\nThese are the building blocks for creating MCP servers and clients with FastMCP.\n\n### The `FastMCP` Server\n\nThe central object representing your MCP application. It holds your tools, resources, and prompts, manages connections, and can be configured with settings like [authentication providers](https://gofastmcp.com/servers/fastmcp#authentication).\n\n```python\nfrom fastmcp import FastMCP\n\n# Create a server instance\nmcp = FastMCP(name=\"MyAssistantServer\")\n```\n\nLearn more in the [**FastMCP Server Documentation**](https://gofastmcp.com/servers/fastmcp).\n\n### Tools\n\nTools allow LLMs to perform actions by executing your Python functions (sync or async). Ideal for computations, API calls, or side effects (like `POST`/`PUT`). FastMCP handles schema generation from type hints and docstrings. Tools can return various types, including text, JSON-serializable objects, and even images using the [`fastmcp.Image`](https://gofastmcp.com/servers/tools#return-values) helper.\n\n```python\n@mcp.tool()\ndef multiply(a: float, b: float) -\u003e float:\n    \"\"\"Multiplies two numbers.\"\"\"\n    return a * b\n```\n\nLearn more in the [**Tools Documentation**](https://gofastmcp.com/servers/tools).\n\n### Resources \u0026 Templates\n\nResources expose read-only data sources (like `GET` requests). Use `@mcp.resource(\"your://uri\")`. Use `{placeholders}` in the URI to create dynamic templates that accept parameters, allowing clients to request specific data subsets.\n\n```python\n# Static resource\n@mcp.resource(\"config://version\")\ndef get_version(): \n    return \"2.0.1\"\n\n# Dynamic resource template\n@mcp.resource(\"users://{user_id}/profile\")\ndef get_profile(user_id: int):\n    # Fetch profile for user_id...\n    return {\"name\": f\"User {user_id}\", \"status\": \"active\"}\n```\n\nLearn more in the [**Resources \u0026 Templates Documentation**](https://gofastmcp.com/servers/resources).\n\n### Prompts\n\nPrompts define reusable message templates to guide LLM interactions. Decorate functions with `@mcp.prompt()`. Return strings or `Message` objects.\n\n```python\n@mcp.prompt()\ndef summarize_request(text: str) -\u003e str:\n    \"\"\"Generate a prompt asking for a summary.\"\"\"\n    return f\"Please summarize the following text:\\n\\n{text}\"\n```\n\nLearn more in the [**Prompts Documentation**](https://gofastmcp.com/servers/prompts).\n\n### Context\n\nAccess MCP session capabilities within your tools, resources, or prompts by adding a `ctx: Context` parameter. Context provides methods for:\n*   **Logging:** Log messages to MCP clients with `ctx.info()`, `ctx.error()`, etc.\n*   **LLM Sampling:** Use `ctx.sample()` to request completions from the client's LLM.\n*   **HTTP Request:** Use `ctx.http_request()` to make HTTP requests to other servers.\n*   **Resource Access:** Use `ctx.read_resource()` to access resources on the server\n*   **Progress Reporting:** Use `ctx.report_progress()` to report progress to the client.\n*   and more...\n\nTo access the context, add a parameter annotated as `Context` to any mcp-decorated function. FastMCP will automatically inject the correct context object when the function is called.\n\n```python\nfrom fastmcp import FastMCP, Context\n\nmcp = FastMCP(\"My MCP Server\")\n\n@mcp.tool()\nasync def process_data(uri: str, ctx: Context):\n    # Log a message to the client\n    await ctx.info(f\"Processing {uri}...\")\n\n    # Read a resource from the server\n    data = await ctx.read_resource(uri)\n\n    # Ask client LLM to summarize the data\n    summary = await ctx.sample(f\"Summarize: {data.content[:500]}\")\n\n    # Return the summary\n    return summary.text\n```\n\nLearn more in the [**Context Documentation**](https://gofastmcp.com/servers/context).\n\n### MCP Clients\n\nInteract with *any* MCP server programmatically using the `fastmcp.Client`. It supports various transports (Stdio, SSE, In-Memory) and often auto-detects the correct one. The client can also handle advanced patterns like server-initiated **LLM sampling requests** if you provide an appropriate handler.\n\nCritically, the client allows for efficient **in-memory testing** of your servers by connecting directly to a `FastMCP` server instance via the `FastMCPTransport`, eliminating the need for process management or network calls during tests.\n\n```python\nfrom fastmcp import Client\n\nasync def main():\n    # Connect via stdio to a local script\n    async with Client(\"my_server.py\") as client:\n        tools = await client.list_tools()\n        print(f\"Available tools: {tools}\")\n        result = await client.call_tool(\"add\", {\"a\": 5, \"b\": 3})\n        print(f\"Result: {result.text}\")\n\n    # Connect via SSE\n    async with Client(\"http://localhost:8000/sse\") as client:\n        # ... use the client\n        pass\n```\n\nTo use clients to test servers, use the following pattern:\n\n```python\nfrom fastmcp import FastMCP, Client\n\nmcp = FastMCP(\"My MCP Server\")\n\nasync def main():\n    # Connect via in-memory transport\n    async with Client(mcp) as client:\n        # ... use the client\n```\n\nLearn more in the [**Client Documentation**](https://gofastmcp.com/clients/client) and [**Transports Documentation**](https://gofastmcp.com/clients/transports).\n\n## Advanced Features\n\nFastMCP introduces powerful ways to structure and deploy your MCP applications.\n\n### Proxy Servers\n\nCreate a FastMCP server that acts as an intermediary for another local or remote MCP server using `FastMCP.from_client()`. This is especially useful for bridging transports (e.g., remote SSE to local Stdio) or adding a layer of logic to a server you don't control.\n\nLearn more in the [**Proxying Documentation**](https://gofastmcp.com/patterns/proxy).\n\n### Composing MCP Servers\n\nBuild modular applications by mounting multiple `FastMCP` instances onto a parent server using `mcp.mount()` (live link) or `mcp.import_server()` (static copy).\n\nLearn more in the [**Composition Documentation**](https://gofastmcp.com/patterns/composition).\n\n### OpenAPI \u0026 FastAPI Generation\n\nAutomatically generate FastMCP servers from existing OpenAPI specifications (`FastMCP.from_openapi()`) or FastAPI applications (`FastMCP.from_fastapi()`), instantly bringing your web APIs to the MCP ecosystem.\n\nLearn more: [**OpenAPI Integration**](https://gofastmcp.com/patterns/openapi) | [**FastAPI Integration**](https://gofastmcp.com/patterns/fastapi).\n\n## Running Your Server\n\nThe main way to run a FastMCP server is by calling the `run()` method on your server instance:\n\n```python\n# server.py\nfrom fastmcp import FastMCP\n\nmcp = FastMCP(\"Demo 🚀\")\n\n@mcp.tool()\ndef hello(name: str) -\u003e str:\n    return f\"Hello, {name}!\"\n\nif __name__ == \"__main__\":\n    mcp.run()  # Default: uses STDIO transport\n```\n\nFastMCP supports three transport protocols:\n\n**STDIO (Default)**: Best for local tools and command-line scripts.\n```python\nmcp.run(transport=\"stdio\")  # Default, so transport argument is optional\n```\n\n**Streamable HTTP**: Recommended for web deployments.\n```python\nmcp.run(transport=\"streamable-http\", host=\"127.0.0.1\", port=8000, path=\"/mcp\")\n```\n\n**SSE**: For compatibility with existing SSE clients.\n```python\nmcp.run(transport=\"sse\", host=\"127.0.0.1\", port=8000)\n```\n\nSee the [**Running Server Documentation**](https://gofastmcp.com/deployment/running-server) for more details.\n\n## Contributing\n\nContributions are the core of open source! We welcome improvements and features.\n\n### Prerequisites\n\n*   Python 3.10+\n*   [uv](https://docs.astral.sh/uv/) (Recommended for environment management)\n\n### Setup\n\n1. Clone the repository: \n   ```bash\n   git clone https://github.com/jlowin/fastmcp.git \n   cd fastmcp\n   ```\n2. Create and sync the environment: \n   ```bash\n   uv sync\n   ```\n   This installs all dependencies, including dev tools.\n   \n3. Activate the virtual environment (e.g., `source .venv/bin/activate` or via your IDE).\n\n### Unit Tests\n\nFastMCP has a comprehensive unit test suite. All PRs must introduce or update tests as appropriate and pass the full suite.\n\nRun tests using pytest:\n```bash\npytest\n```\nor if you want an overview of the code coverage\n```bash\nuv run pytest --cov=src --cov=examples --cov-report=html\n```\n\n### Static Checks\n\nFastMCP uses `pre-commit` for code formatting, linting, and type-checking. All PRs must pass these checks (they run automatically in CI).\n\nInstall the hooks locally:\n```bash\nuv run pre-commit install\n```\nThe hooks will now run automatically on `git commit`. You can also run them manually at any time:\n```bash\npre-commit run --all-files\n# or via uv\nuv run pre-commit run --all-files\n```\n\n### Pull Requests\n\n1.  Fork the repository on GitHub.\n2.  Create a feature branch from `main`.\n3.  Make your changes, including tests and documentation updates.\n4.  Ensure tests and pre-commit hooks pass.\n5.  Commit your changes and push to your fork.\n6.  Open a pull request against the `main` branch of `jlowin/fastmcp`.\n\nPlease open an issue or discussion for questions or suggestions before starting significant work!","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjlowin%2Ffastmcp","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fjlowin%2Ffastmcp","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjlowin%2Ffastmcp/lists"}