mirror of
https://github.com/PrefectHQ/fastmcp.git
synced 2026-08-22 13:34:17 +02:00
Update readme
This commit is contained in:
Jeremiah Lowin
parent
466ab331e9
commit
f1deaf94a5
2 changed files with 374 additions and 314 deletions
741
README.md
741
README.md
|
|
@ -1,101 +1,105 @@
|
|||
<div align="center">
|
||||
|
||||
### 🎉 FastMCP has been added to the official MCP SDK! 🎉
|
||||
|
||||
You can now find FastMCP as part of the official Model Context Protocol Python SDK:
|
||||
|
||||
👉 [github.com/modelcontextprotocol/python-sdk](https://github.com/modelcontextprotocol/python-sdk)
|
||||
|
||||
*Please note: this repository is no longer maintained.*
|
||||
|
||||
---
|
||||
|
||||
|
||||
</br></br></br>
|
||||
|
||||
</div>
|
||||
|
||||
<div align="center">
|
||||
|
||||
<!-- omit in toc -->
|
||||
# FastMCP 🚀
|
||||
<strong>The fast, Pythonic way to build MCP servers.</strong>
|
||||
# FastMCP v2 🚀
|
||||
<strong>Build and interact with MCP applications the fast, Pythonic way.</strong>
|
||||
|
||||
[](https://pypi.org/project/fastmcp)
|
||||
[](https://github.com/jlowin/fastmcp/actions/workflows/run-tests.yml)
|
||||
[](https://github.com/jlowin/fastmcp/blob/main/LICENSE)
|
||||
|
||||
|
||||
</div>
|
||||
|
||||
[Model Context Protocol (MCP)](https://modelcontextprotocol.io) servers are a new, standardized way to provide context and tools to your LLMs, and FastMCP makes building MCP servers simple and intuitive. Create tools, expose resources, and define prompts with clean, Pythonic code:
|
||||
[Model Context Protocol (MCP)](https://modelcontextprotocol.io) servers are a standardized way to provide context and tools to your LLMs, and FastMCP makes building *and interacting with* them simple and intuitive. Create tools, expose resources, define prompts, and connect components with clean, Pythonic code.
|
||||
|
||||
```python
|
||||
# demo.py
|
||||
|
||||
# server.py
|
||||
from fastmcp import FastMCP
|
||||
|
||||
|
||||
mcp = FastMCP("Demo 🚀")
|
||||
|
||||
|
||||
@mcp.tool()
|
||||
def add(a: int, b: int) -> int:
|
||||
"""Add two numbers"""
|
||||
return a + b
|
||||
|
||||
if __name__ == "__main__":
|
||||
mcp.run()
|
||||
```
|
||||
|
||||
That's it! Give Claude access to the server by running:
|
||||
|
||||
Run it locally for testing:
|
||||
```bash
|
||||
fastmcp install demo.py
|
||||
fastmcp dev server.py
|
||||
```
|
||||
|
||||
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.
|
||||
Install it for use with Claude Desktop:
|
||||
```bash
|
||||
fastmcp install server.py
|
||||
```
|
||||
|
||||
FastMCP handles the complex protocol details and server management, letting you focus on building great tools and applications. It's designed to feel natural to Python developers.
|
||||
|
||||
### Key features:
|
||||
* **Fast**: High-level interface means less code and faster development
|
||||
* **Simple**: Build MCP servers with minimal boilerplate
|
||||
* **Pythonic**: Feels natural to Python developers
|
||||
* **Complete***: FastMCP aims to provide a full implementation of the core MCP specification
|
||||
## Key Features:
|
||||
|
||||
(\*emphasis on *aims*)
|
||||
* **Simple Server Creation:** Build MCP servers with minimal boilerplate using intuitive decorators (`@tool`, `@resource`, `@prompt`).
|
||||
* **Powerful Clients:** Programmatically interact with *any* MCP server, regardless of how it was built.
|
||||
* **Flexible Proxying:** Create proxy servers to expose existing MCP servers or clients with modifications, or **convert between transport protocols** (e.g., expose a Stdio server via SSE for web access).
|
||||
* **Server Mounting:** Compose complex applications by mounting multiple FastMCP servers together.
|
||||
* **API Generation:** Automatically create MCP servers from existing **OpenAPI specifications** or **FastAPI applications**.
|
||||
* **Pythonic Interface:** Designed with familiar Python patterns like decorators and type hints.
|
||||
* **Context Injection:** Easily access core MCP capabilities like sampling, logging, and progress reporting within your functions.
|
||||
|
||||
🚨 🚧 🏗️ *FastMCP is under active development, as is the MCP specification itself. Core features are working but some advanced capabilities are still in progress.*
|
||||
---
|
||||
|
||||
### FastMCP v1 and v2
|
||||
|
||||
FastMCP v1's core approach of using the `@tool`, `@resource`, `@prompt` decorators with the `FastMCP` class proved so successful that it became part of the official Model Context Protocol Python SDK! For basic server creation, you can use the upstream version by importing `mcp.server.fastmcp.FastMCP`.
|
||||
|
||||
👉 The **MCP Python SDK** can be found at [github.com/modelcontextprotocol/python-sdk](https://github.com/modelcontextprotocol/python-sdk)
|
||||
|
||||
**FastMCP v2 builds upon v1's foundation** and adds the advanced features listed above (Client, Proxy, Mounting, API Generation, and more).
|
||||
|
||||
* **Need just the basics?** Use FastMCP v1 (the official SDK).
|
||||
* **Need advanced features like clients, proxies, or mounting?** Use FastMCP v2 (this library).
|
||||
|
||||
---
|
||||
|
||||
<!-- omit in toc -->
|
||||
## Table of Contents
|
||||
|
||||
- [Key Features:](#key-features)
|
||||
- [FastMCP v1 and v2](#fastmcp-v1-and-v2)
|
||||
- [Installation](#installation)
|
||||
- [Quickstart](#quickstart)
|
||||
- [What is MCP?](#what-is-mcp)
|
||||
- [Core Concepts](#core-concepts)
|
||||
- [Server](#server)
|
||||
- [Resources](#resources)
|
||||
- [Core Concepts (The Foundation)](#core-concepts-the-foundation)
|
||||
- [The `FastMCP` Server](#the-fastmcp-server)
|
||||
- [Tools](#tools)
|
||||
- [Resources](#resources)
|
||||
- [Prompts](#prompts)
|
||||
- [Images](#images)
|
||||
- [Context](#context)
|
||||
- [Images](#images)
|
||||
- [Advanced Features](#advanced-features)
|
||||
- [MCP Client](#mcp-client)
|
||||
- [Proxy Servers](#proxy-servers)
|
||||
- [Composing MCP Servers](#composing-mcp-servers)
|
||||
- [OpenAPI \& FastAPI Generation](#openapi--fastapi-generation)
|
||||
- [Running Your Server](#running-your-server)
|
||||
- [Development Mode (Recommended for Building \& Testing)](#development-mode-recommended-for-building--testing)
|
||||
- [Claude Desktop Integration (For Regular Use)](#claude-desktop-integration-for-regular-use)
|
||||
- [Direct Execution (For Advanced Use Cases)](#direct-execution-for-advanced-use-cases)
|
||||
- [Server Object Names](#server-object-names)
|
||||
- [Examples](#examples)
|
||||
- [Echo Server](#echo-server)
|
||||
- [SQLite Explorer](#sqlite-explorer)
|
||||
- [Contributing](#contributing)
|
||||
- [Prerequisites](#prerequisites)
|
||||
- [Installation](#installation-1)
|
||||
- [Testing](#testing)
|
||||
- [Formatting](#formatting)
|
||||
- [Opening a Pull Request](#opening-a-pull-request)
|
||||
- [Prerequisites](#prerequisites)
|
||||
- [Setup](#setup)
|
||||
- [Testing](#testing)
|
||||
- [Formatting \& Linting](#formatting--linting)
|
||||
- [Pull Requests](#pull-requests)
|
||||
|
||||
## Installation
|
||||
|
||||
We strongly recommend installing FastMCP with [uv](https://docs.astral.sh/uv/), as it is required for deploying servers:
|
||||
We strongly recommend installing FastMCP with [uv](https://docs.astral.sh/uv/), as it is required for deploying servers via the CLI:
|
||||
|
||||
```bash
|
||||
uv pip install fastmcp
|
||||
|
|
@ -103,10 +107,13 @@ uv pip install fastmcp
|
|||
|
||||
Note: on macOS, uv may need to be installed with Homebrew (`brew install uv`) in order to make it available to the Claude Desktop app.
|
||||
|
||||
Alternatively, to use the SDK without deploying, you may use pip:
|
||||
|
||||
For development, install with:
|
||||
```bash
|
||||
pip install fastmcp
|
||||
# Clone the repo first
|
||||
git clone https://github.com/jlowin/fastmcp.git
|
||||
cd fastmcp
|
||||
# Install with dev dependencies
|
||||
uv sync --dev
|
||||
```
|
||||
|
||||
## Quickstart
|
||||
|
|
@ -115,21 +122,17 @@ Let's create a simple MCP server that exposes a calculator tool and some data:
|
|||
|
||||
```python
|
||||
# server.py
|
||||
|
||||
from fastmcp import FastMCP
|
||||
|
||||
|
||||
# Create an MCP server
|
||||
mcp = FastMCP("Demo")
|
||||
|
||||
|
||||
# Add an addition tool
|
||||
@mcp.tool()
|
||||
def add(a: int, b: int) -> int:
|
||||
"""Add two numbers"""
|
||||
return a + b
|
||||
|
||||
|
||||
# Add a dynamic greeting resource
|
||||
@mcp.resource("greeting://{name}")
|
||||
def get_greeting(name: str) -> str:
|
||||
|
|
@ -153,19 +156,20 @@ fastmcp dev server.py
|
|||
|
||||
The [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:
|
||||
|
||||
- Expose data through **Resources** (think of these sort of like GET endpoints; they are used to load information into the LLM's context)
|
||||
- Provide functionality through **Tools** (sort of like POST endpoints; they are used to execute code or otherwise produce a side effect)
|
||||
- Define interaction patterns through **Prompts** (reusable templates for LLM interactions)
|
||||
- Expose data through **Resources** (think GET endpoints; load info into context)
|
||||
- Provide functionality through **Tools** (think POST/PUT endpoints; execute actions)
|
||||
- Define interaction patterns through **Prompts** (reusable templates)
|
||||
- And more!
|
||||
|
||||
There is a low-level [Python SDK](https://github.com/modelcontextprotocol/python-sdk) available for implementing the protocol directly, but FastMCP aims to make that easier by providing a high-level, Pythonic interface.
|
||||
FastMCP provides a high-level, Pythonic interface for building and interacting with these servers.
|
||||
|
||||
## Core Concepts
|
||||
## Core Concepts (The Foundation)
|
||||
|
||||
These are the building blocks for creating MCP servers, using the familiar decorator-based approach.
|
||||
|
||||
### Server
|
||||
### The `FastMCP` Server
|
||||
|
||||
The FastMCP server is your core interface to the MCP protocol. It handles connection management, protocol compliance, and message routing:
|
||||
The central object representing your MCP application. It handles connections, protocol details, and routing.
|
||||
|
||||
```python
|
||||
from fastmcp import FastMCP
|
||||
|
|
@ -173,391 +177,440 @@ from fastmcp import FastMCP
|
|||
# Create a named server
|
||||
mcp = FastMCP("My App")
|
||||
|
||||
# Specify dependencies for deployment and development
|
||||
# Specify dependencies needed when deployed via `fastmcp install`
|
||||
mcp = FastMCP("My App", dependencies=["pandas", "numpy"])
|
||||
```
|
||||
|
||||
### Resources
|
||||
|
||||
Resources are how you expose data to LLMs. They're similar to GET endpoints in a REST API - they provide data but shouldn't perform significant computation or have side effects. Some examples:
|
||||
|
||||
- File contents
|
||||
- Database schemas
|
||||
- API responses
|
||||
- System information
|
||||
|
||||
Resources can be static:
|
||||
```python
|
||||
@mcp.resource("config://app")
|
||||
def get_config() -> str:
|
||||
"""Static configuration data"""
|
||||
return "App configuration here"
|
||||
```
|
||||
|
||||
Or dynamic with parameters (FastMCP automatically handles these as MCP templates):
|
||||
```python
|
||||
@mcp.resource("users://{user_id}/profile")
|
||||
def get_user_profile(user_id: str) -> str:
|
||||
"""Dynamic user data"""
|
||||
return f"Profile data for user {user_id}"
|
||||
```
|
||||
|
||||
### Tools
|
||||
|
||||
Tools let LLMs take actions through your server. Unlike resources, tools are expected to perform computation and have side effects. They're similar to POST endpoints in a REST API.
|
||||
Tools allow LLMs to perform actions by executing your Python functions. They are ideal for tasks that involve computation, external API calls, or side effects.
|
||||
|
||||
Simple calculation example:
|
||||
```python
|
||||
@mcp.tool()
|
||||
def calculate_bmi(weight_kg: float, height_m: float) -> float:
|
||||
"""Calculate BMI given weight in kg and height in meters"""
|
||||
return weight_kg / (height_m ** 2)
|
||||
```
|
||||
Decorate synchronous or asynchronous functions with `@mcp.tool()`. FastMCP automatically generates the necessary MCP schema based on type hints and docstrings. Pydantic models can be used for complex inputs.
|
||||
|
||||
HTTP request example:
|
||||
```python
|
||||
import httpx
|
||||
from pydantic import BaseModel
|
||||
|
||||
class UserInfo(BaseModel):
|
||||
user_id: int
|
||||
notify: bool = False
|
||||
|
||||
@mcp.tool()
|
||||
async def fetch_weather(city: str) -> str:
|
||||
"""Fetch current weather for a city"""
|
||||
async with httpx.AsyncClient() as client:
|
||||
response = await client.get(
|
||||
f"https://api.weather.com/{city}"
|
||||
)
|
||||
return response.text
|
||||
async def send_notification(user: UserInfo, message: str) -> dict:
|
||||
"""Sends a notification to a user if requested."""
|
||||
if user.notify:
|
||||
# Simulate sending notification
|
||||
print(f"Notifying user {user.user_id}: {message}")
|
||||
return {"status": "sent", "user_id": user.user_id}
|
||||
return {"status": "skipped", "user_id": user.user_id}
|
||||
|
||||
@mcp.tool()
|
||||
def get_stock_price(ticker: str) -> float:
|
||||
"""Gets the current price for a stock ticker."""
|
||||
# Replace with actual API call
|
||||
prices = {"AAPL": 180.50, "GOOG": 140.20}
|
||||
return prices.get(ticker.upper(), 0.0)
|
||||
```
|
||||
|
||||
Complex input handling example:
|
||||
### Resources
|
||||
|
||||
Resources expose data to LLMs. They should primarily provide information without significant computation or side effects (like GET requests).
|
||||
|
||||
Decorate functions with `@mcp.resource("your://uri")`. Use curly braces `{}` in the URI to define dynamic resources (templates) where parts of the URI become function parameters.
|
||||
|
||||
```python
|
||||
from pydantic import BaseModel, Field
|
||||
from typing import Annotated
|
||||
# Static resource returning simple text
|
||||
@mcp.resource("config://app-version")
|
||||
def get_app_version() -> str:
|
||||
"""Returns the application version."""
|
||||
return "v2.1.0"
|
||||
|
||||
class ShrimpTank(BaseModel):
|
||||
class Shrimp(BaseModel):
|
||||
name: Annotated[str, Field(max_length=10)]
|
||||
# Dynamic resource template expecting a 'user_id' from the URI
|
||||
@mcp.resource("db://users/{user_id}/email")
|
||||
async def get_user_email(user_id: str) -> str:
|
||||
"""Retrieves the email address for a given user ID."""
|
||||
# Replace with actual database lookup
|
||||
emails = {"123": "alice@example.com", "456": "bob@example.com"}
|
||||
return emails.get(user_id, "not_found@example.com")
|
||||
|
||||
shrimp: list[Shrimp]
|
||||
|
||||
@mcp.tool()
|
||||
def name_shrimp(
|
||||
tank: ShrimpTank,
|
||||
# You can use pydantic Field in function signatures for validation.
|
||||
extra_names: Annotated[list[str], Field(max_length=10)],
|
||||
) -> list[str]:
|
||||
"""List all shrimp names in the tank"""
|
||||
return [shrimp.name for shrimp in tank.shrimp] + extra_names
|
||||
# Resource returning JSON data
|
||||
@mcp.resource("data://product-categories")
|
||||
def get_categories() -> list[str]:
|
||||
"""Returns a list of available product categories."""
|
||||
return ["Electronics", "Books", "Home Goods"]
|
||||
```
|
||||
|
||||
### Prompts
|
||||
|
||||
Prompts are reusable templates that help LLMs interact with your server effectively. They're like "best practices" encoded into your server. A prompt can be as simple as a string:
|
||||
Prompts define reusable templates or interaction patterns for the LLM. They help guide the LLM on how to use your server's capabilities effectively.
|
||||
|
||||
```python
|
||||
@mcp.prompt()
|
||||
def review_code(code: str) -> str:
|
||||
return f"Please review this code:\n\n{code}"
|
||||
```
|
||||
Decorate functions with `@mcp.prompt()`. The function should return the desired prompt content, which can be a simple string, a `Message` object (like `UserMessage` or `AssistantMessage`), or a list of these.
|
||||
|
||||
Or a more structured sequence of messages:
|
||||
```python
|
||||
from fastmcp.prompts.base import UserMessage, AssistantMessage
|
||||
|
||||
@mcp.prompt()
|
||||
def debug_error(error: str) -> list[Message]:
|
||||
def ask_review(code_snippet: str) -> str:
|
||||
"""Generates a standard code review request."""
|
||||
return f"Please review the following code snippet for potential bugs and style issues:\n```python\n{code_snippet}\n```"
|
||||
|
||||
@mcp.prompt()
|
||||
def debug_session_start(error_message: str) -> list[Message]:
|
||||
"""Initiates a debugging help session."""
|
||||
return [
|
||||
UserMessage("I'm seeing this error:"),
|
||||
UserMessage(error),
|
||||
AssistantMessage("I'll help debug that. What have you tried so far?")
|
||||
UserMessage(f"I encountered an error:\n{error_message}"),
|
||||
AssistantMessage("Okay, I can help with that. Can you provide the full traceback and tell me what you were trying to do?")
|
||||
]
|
||||
```
|
||||
|
||||
### Context
|
||||
|
||||
Gain access to MCP server capabilities *within* your tool or resource functions by adding a parameter type-hinted with `fastmcp.Context`.
|
||||
|
||||
```python
|
||||
from fastmcp import Context, FastMCP
|
||||
|
||||
mcp = FastMCP("Context Demo")
|
||||
|
||||
@mcp.resource("system://status")
|
||||
async def get_system_status(ctx: Context) -> dict:
|
||||
"""Checks system status and logs information."""
|
||||
await ctx.info("Checking system status...")
|
||||
# Perform checks
|
||||
await ctx.report_progress(1, 1) # Report completion
|
||||
return {"status": "OK", "load": 0.5, "client": ctx.client_id}
|
||||
|
||||
@mcp.tool()
|
||||
async def process_large_file(file_uri: str, ctx: Context) -> str:
|
||||
"""Processes a large file, reporting progress and reading resources."""
|
||||
await ctx.info(f"Starting processing for {file_uri}")
|
||||
# Read the resource using the context
|
||||
file_content_resource = await ctx.read_resource(file_uri)
|
||||
file_content = file_content_resource[0].content # Assuming single text content
|
||||
lines = file_content.splitlines()
|
||||
total_lines = len(lines)
|
||||
|
||||
for i, line in enumerate(lines):
|
||||
# Process line...
|
||||
if (i + 1) % 100 == 0: # Report progress every 100 lines
|
||||
await ctx.report_progress(i + 1, total_lines)
|
||||
|
||||
await ctx.info(f"Finished processing {file_uri}")
|
||||
return f"Processed {total_lines} lines."
|
||||
|
||||
```
|
||||
|
||||
The `Context` object provides:
|
||||
* Logging: `ctx.debug()`, `ctx.info()`, `ctx.warning()`, `ctx.error()`
|
||||
* Progress Reporting: `ctx.report_progress(current, total)`
|
||||
* Resource Access: `await ctx.read_resource(uri)`
|
||||
* Request Info: `ctx.request_id`, `ctx.client_id`
|
||||
* Sampling (Advanced): `await ctx.sample(...)` to ask the connected LLM client for completions.
|
||||
|
||||
### Images
|
||||
|
||||
FastMCP provides an `Image` class that automatically handles image data in your server:
|
||||
Easily handle image input and output using the `fastmcp.Image` helper class.
|
||||
|
||||
```python
|
||||
from fastmcp import FastMCP, Image
|
||||
from PIL import Image as PILImage
|
||||
import io
|
||||
|
||||
mcp = FastMCP("Image Demo")
|
||||
|
||||
@mcp.tool()
|
||||
def create_thumbnail(image_path: str) -> Image:
|
||||
"""Create a thumbnail from an image"""
|
||||
img = PILImage.open(image_path)
|
||||
def create_thumbnail(image_data: Image) -> Image:
|
||||
"""Creates a 100x100 thumbnail from the provided image."""
|
||||
img = PILImage.open(io.BytesIO(image_data.data)) # Assumes image_data received as Image with bytes
|
||||
img.thumbnail((100, 100))
|
||||
|
||||
# FastMCP automatically handles conversion and MIME types
|
||||
return Image(data=img.tobytes(), format="png")
|
||||
buffer = io.BytesIO()
|
||||
img.save(buffer, format="PNG")
|
||||
# Return a new Image object with the thumbnail data
|
||||
return Image(data=buffer.getvalue(), format="png")
|
||||
|
||||
@mcp.tool()
|
||||
def load_image(path: str) -> Image:
|
||||
"""Load an image from disk"""
|
||||
# FastMCP handles reading and format detection
|
||||
def load_image_from_disk(path: str) -> Image:
|
||||
"""Loads an image from the specified path."""
|
||||
# Handles reading file and detecting format based on extension
|
||||
return Image(path=path)
|
||||
```
|
||||
FastMCP handles the conversion to/from the base64-encoded format required by the MCP protocol.
|
||||
|
||||
Images can be used as the result of both tools and resources.
|
||||
## Advanced Features
|
||||
|
||||
### Context
|
||||
Building on the core concepts, FastMCP v2 introduces powerful features for more complex scenarios:
|
||||
|
||||
The Context object gives your tools and resources access to MCP capabilities. To use it, add a parameter annotated with `fastmcp.Context`:
|
||||
### MCP Client
|
||||
|
||||
The client allows your Python code to interact with *any* MCP server, whether it's built with FastMCP, the official SDK, or another implementation. This is essential for testing, building meta-tools, or integrating MCP servers.
|
||||
|
||||
```python
|
||||
from fastmcp import FastMCP, Context
|
||||
import asyncio
|
||||
from fastmcp import Client
|
||||
from fastmcp.client.transports import StdioTransport # Example transport
|
||||
|
||||
@mcp.tool()
|
||||
async def long_task(files: list[str], ctx: Context) -> str:
|
||||
"""Process multiple files with progress tracking"""
|
||||
for i, file in enumerate(files):
|
||||
ctx.info(f"Processing {file}")
|
||||
await ctx.report_progress(i, len(files))
|
||||
|
||||
# Read another resource if needed
|
||||
data = await ctx.read_resource(f"file://{file}")
|
||||
|
||||
return "Processing complete"
|
||||
async def main():
|
||||
# Connect to a server running via standard I/O
|
||||
# Replace with the actual command to start your target server
|
||||
client = Client(StdioTransport(command="python", args=["path/to/target_server.py"]))
|
||||
|
||||
async with client:
|
||||
# Discover tools
|
||||
tools_result = await client.list_tools()
|
||||
print(f"Available Tools: {[t.name for t in tools_result.tools]}")
|
||||
|
||||
# Call a tool
|
||||
add_result = await client.call_tool("add", {"a": 10, "b": 5})
|
||||
print(f"Result of add(10, 5): {add_result.content[0].text}") # Output: 15
|
||||
|
||||
# Read a resource
|
||||
greeting = await client.read_resource("greeting://Client")
|
||||
print(f"Resource Content: {greeting.contents[0].text}") # Output: Hello, Client!
|
||||
|
||||
if __name__ == "__main__":
|
||||
asyncio.run(main())
|
||||
```
|
||||
|
||||
The Context object provides:
|
||||
- Progress reporting through `report_progress()`
|
||||
- Logging via `debug()`, `info()`, `warning()`, and `error()`
|
||||
- Resource access through `read_resource()`
|
||||
- Request metadata via `request_id` and `client_id`
|
||||
The client supports various transports (`WSTransport`, `SSETransport`, `StdioTransport`, `FastMCPTransport`) and intelligently infers the correct one based on the connection information provided (URL, `FastMCP` instance, command arguments, etc.).
|
||||
|
||||
## Running Your Server
|
||||
### Proxy Servers
|
||||
|
||||
There are three main ways to use your FastMCP server, each suited for different stages of development:
|
||||
Create a FastMCP server that acts as an intermediary, proxying requests to another MCP endpoint (which could be a server or another client connection).
|
||||
|
||||
### Development Mode (Recommended for Building & Testing)
|
||||
**Use Cases:**
|
||||
|
||||
The fastest way to test and debug your server is with the MCP Inspector:
|
||||
* **Transport Conversion:** Expose a server running on Stdio (like many local tools) over SSE or WebSockets, making it accessible to web clients or Claude Desktop.
|
||||
* **Adding Functionality:** Wrap an existing server to add authentication, request logging, or modified tool behavior.
|
||||
* **Aggregating Servers:** Combine multiple backend MCP servers behind a single proxy interface (though `mount` might be simpler for this).
|
||||
|
||||
```bash
|
||||
fastmcp dev server.py
|
||||
```python
|
||||
import asyncio
|
||||
from fastmcp import FastMCP, Client
|
||||
from fastmcp.client.transports import PythonStdioTransport
|
||||
|
||||
# Create a client that connects to the original server
|
||||
proxy_client = Client(
|
||||
transport=PythonStdioTransport('path/to/original_stdio_server.py'),
|
||||
)
|
||||
|
||||
# Create a proxy server that connects to the client and exposes its capabilities
|
||||
proxy = FastMCP.as_proxy(proxy_client, name="Stdio-to-SSE Proxy")
|
||||
|
||||
if __name__ == "__main__":
|
||||
proxy.run(transport='sse')
|
||||
```
|
||||
|
||||
This launches a web interface where you can:
|
||||
- Test your tools and resources interactively
|
||||
- See detailed logs and error messages
|
||||
- Monitor server performance
|
||||
- Set environment variables for testing
|
||||
`FastMCP.as_proxy` is an `async` classmethod. It connects to the target, discovers its capabilities, and dynamically builds the proxy server instance.
|
||||
|
||||
During development, you can:
|
||||
- Add dependencies with `--with`:
|
||||
```bash
|
||||
fastmcp dev server.py --with pandas --with numpy
|
||||
```
|
||||
- Mount your local code for live updates:
|
||||
```bash
|
||||
fastmcp dev server.py --with-editable .
|
||||
```
|
||||
|
||||
### Claude Desktop Integration (For Regular Use)
|
||||
|
||||
Once your server is ready, install it in Claude Desktop to use it with Claude:
|
||||
### Composing MCP Servers
|
||||
|
||||
```bash
|
||||
fastmcp install server.py
|
||||
```
|
||||
|
||||
Your server will run in an isolated environment with:
|
||||
- Automatic installation of dependencies specified in your FastMCP instance:
|
||||
```python
|
||||
mcp = FastMCP("My App", dependencies=["pandas", "numpy"])
|
||||
```
|
||||
- Custom naming via `--name`:
|
||||
```bash
|
||||
fastmcp install server.py --name "My Analytics Server"
|
||||
```
|
||||
- Environment variable management:
|
||||
```bash
|
||||
# Set variables individually
|
||||
fastmcp install server.py -e API_KEY=abc123 -e DB_URL=postgres://...
|
||||
|
||||
# Or load from a .env file
|
||||
fastmcp install server.py -f .env
|
||||
```
|
||||
|
||||
### Direct Execution (For Advanced Use Cases)
|
||||
|
||||
For advanced scenarios like custom deployments or running without Claude, you can execute your server directly:
|
||||
Structure larger MCP applications by creating modular FastMCP servers and "mounting" them onto a parent server. This automatically handles prefixing for tool names and resource URIs, preventing conflicts.
|
||||
|
||||
```python
|
||||
from fastmcp import FastMCP
|
||||
|
||||
mcp = FastMCP("My App")
|
||||
# --- Weather MCP ---
|
||||
weather_mcp = FastMCP("Weather Service")
|
||||
|
||||
@weather_mcp.tool()
|
||||
def get_forecast(city: str):
|
||||
return f"Sunny in {city}"
|
||||
|
||||
@weather_mcp.resource("data://temp/{city}")
|
||||
def get_temp(city: str):
|
||||
return 25.0
|
||||
|
||||
# --- News MCP ---
|
||||
news_mcp = FastMCP("News Service")
|
||||
|
||||
@news_mcp.tool()
|
||||
def fetch_headlines():
|
||||
return ["Big news!", "Other news"]
|
||||
|
||||
@news_mcp.resource("data://latest_story")
|
||||
def get_story():
|
||||
return "A story happened."
|
||||
|
||||
# --- Composite MCP ---
|
||||
|
||||
mcp = FastMCP("Composite")
|
||||
|
||||
# Mount sub-apps with prefixes
|
||||
mcp.mount("weather", weather_mcp) # Tools prefixed "weather/", resources prefixed "weather+"
|
||||
mcp.mount("news", news_mcp) # Tools prefixed "news/", resources prefixed "news+"
|
||||
|
||||
@mcp.tool()
|
||||
def ping():
|
||||
return "Composite OK"
|
||||
|
||||
|
||||
if __name__ == "__main__":
|
||||
mcp.run()
|
||||
```
|
||||
|
||||
Run it with:
|
||||
```bash
|
||||
# Using the FastMCP CLI
|
||||
fastmcp run server.py
|
||||
This promotes code organization and reusability for complex MCP systems.
|
||||
|
||||
# Or with Python/uv directly
|
||||
python server.py
|
||||
uv run python server.py
|
||||
### OpenAPI & FastAPI Generation
|
||||
|
||||
Leverage your existing web APIs by automatically generating FastMCP servers from them.
|
||||
|
||||
By default, the following rules are applied:
|
||||
- `GET` requests -> MCP resources
|
||||
- `GET` requests with path parameters -> MCP resource templates
|
||||
- All other HTTP methods -> MCP tools
|
||||
|
||||
You can override these rules to customize or even ignore certain endpoints.
|
||||
|
||||
**From FastAPI:**
|
||||
|
||||
```python
|
||||
from fastapi import FastAPI
|
||||
from fastmcp import FastMCP
|
||||
|
||||
# Your existing FastAPI application
|
||||
fastapi_app = FastAPI(title="My Existing API")
|
||||
|
||||
@fastapi_app.get("/status")
|
||||
def get_status():
|
||||
return {"status": "running"}
|
||||
|
||||
@fastapi_app.post("/items")
|
||||
def create_item(name: str, price: float):
|
||||
return {"id": 1, "name": name, "price": price}
|
||||
|
||||
# Generate an MCP server directly from the FastAPI app
|
||||
mcp_server = FastMCP.from_fastapi(fastapi_app)
|
||||
|
||||
if __name__ == "__main__":
|
||||
mcp_server.run()
|
||||
```
|
||||
|
||||
**From an OpenAPI Specification:**
|
||||
|
||||
Note: When running directly, you are responsible for ensuring all dependencies are available in your environment. Any dependencies specified on the FastMCP instance are ignored.
|
||||
```python
|
||||
import httpx
|
||||
import json
|
||||
from fastmcp import FastMCP
|
||||
|
||||
Choose this method when you need:
|
||||
- Custom deployment configurations
|
||||
- Integration with other services
|
||||
- Direct control over the server lifecycle
|
||||
# Load the OpenAPI spec (dict)
|
||||
# with open("my_api_spec.json", "r") as f:
|
||||
# openapi_spec = json.load(f)
|
||||
openapi_spec = { ... } # Your spec dict
|
||||
|
||||
# Create an HTTP client to make requests to the actual API endpoint
|
||||
http_client = httpx.AsyncClient(base_url="https://api.yourservice.com")
|
||||
|
||||
# Generate the MCP server
|
||||
mcp_server = FastMCP.from_openapi(openapi_spec, client=http_client)
|
||||
|
||||
if __name__ == "__main__":
|
||||
mcp_server.run()
|
||||
```
|
||||
|
||||
## Running Your Server
|
||||
|
||||
Choose the method that best suits your needs:
|
||||
|
||||
### Development Mode (Recommended for Building & Testing)
|
||||
|
||||
Use `fastmcp dev` for an interactive testing environment with the MCP Inspector.
|
||||
|
||||
```bash
|
||||
fastmcp dev your_server_file.py
|
||||
# With temporary dependencies
|
||||
fastmcp dev your_server_file.py --with pandas --with numpy
|
||||
# With local package in editable mode
|
||||
fastmcp dev your_server_file.py --with-editable .
|
||||
```
|
||||
|
||||
### Claude Desktop Integration (For Regular Use)
|
||||
|
||||
Use `fastmcp install` to set up your server for persistent use within the Claude Desktop app. It handles creating an isolated environment using `uv`.
|
||||
|
||||
```bash
|
||||
fastmcp install your_server_file.py
|
||||
# With a custom name in Claude
|
||||
fastmcp install your_server_file.py --name "My Analysis Tool"
|
||||
# With extra packages and environment variables
|
||||
fastmcp install server.py --with requests -v API_KEY=123 -f .env
|
||||
```
|
||||
|
||||
### Direct Execution (For Advanced Use Cases)
|
||||
|
||||
Run your server script directly for custom deployments or integrations outside of Claude. You manage the environment and dependencies yourself.
|
||||
|
||||
Add to your `your_server_file.py`:
|
||||
```python
|
||||
if __name__ == "__main__":
|
||||
mcp.run() # Assuming 'mcp' is your FastMCP instance
|
||||
```
|
||||
Run with:
|
||||
```bash
|
||||
python your_server_file.py
|
||||
# or
|
||||
uv run python your_server_file.py
|
||||
```
|
||||
|
||||
### Server Object Names
|
||||
|
||||
All FastMCP commands will look for a server object called `mcp`, `app`, or `server` in your file. If you have a different object name or multiple servers in one file, use the syntax `server.py:my_server`:
|
||||
If your `FastMCP` instance is not named `mcp`, `server`, or `app`, specify it using `file:object` syntax for the `dev` and `install` commands:
|
||||
|
||||
```bash
|
||||
# Using a standard name
|
||||
fastmcp run server.py
|
||||
|
||||
# Using a custom name
|
||||
fastmcp run server.py:my_custom_server
|
||||
fastmcp dev my_module.py:my_mcp_instance
|
||||
fastmcp install api.py:api_app
|
||||
```
|
||||
|
||||
## Examples
|
||||
|
||||
Here are a few examples of FastMCP servers. For more, see the `examples/` directory.
|
||||
Explore the `examples/` directory for code samples demonstrating various features:
|
||||
|
||||
### Echo Server
|
||||
A simple server demonstrating resources, tools, and prompts:
|
||||
|
||||
```python
|
||||
from fastmcp import FastMCP
|
||||
|
||||
mcp = FastMCP("Echo")
|
||||
|
||||
@mcp.resource("echo://{message}")
|
||||
def echo_resource(message: str) -> str:
|
||||
"""Echo a message as a resource"""
|
||||
return f"Resource echo: {message}"
|
||||
|
||||
@mcp.tool()
|
||||
def echo_tool(message: str) -> str:
|
||||
"""Echo a message as a tool"""
|
||||
return f"Tool echo: {message}"
|
||||
|
||||
@mcp.prompt()
|
||||
def echo_prompt(message: str) -> str:
|
||||
"""Create an echo prompt"""
|
||||
return f"Please process this message: {message}"
|
||||
```
|
||||
|
||||
### SQLite Explorer
|
||||
A more complex example showing database integration:
|
||||
|
||||
```python
|
||||
from fastmcp import FastMCP
|
||||
import sqlite3
|
||||
|
||||
mcp = FastMCP("SQLite Explorer")
|
||||
|
||||
@mcp.resource("schema://main")
|
||||
def get_schema() -> str:
|
||||
"""Provide the database schema as a resource"""
|
||||
conn = sqlite3.connect("database.db")
|
||||
schema = conn.execute(
|
||||
"SELECT sql FROM sqlite_master WHERE type='table'"
|
||||
).fetchall()
|
||||
return "\n".join(sql[0] for sql in schema if sql[0])
|
||||
|
||||
@mcp.tool()
|
||||
def query_data(sql: str) -> str:
|
||||
"""Execute SQL queries safely"""
|
||||
conn = sqlite3.connect("database.db")
|
||||
try:
|
||||
result = conn.execute(sql).fetchall()
|
||||
return "\n".join(str(row) for row in result)
|
||||
except Exception as e:
|
||||
return f"Error: {str(e)}"
|
||||
|
||||
@mcp.prompt()
|
||||
def analyze_table(table: str) -> str:
|
||||
"""Create a prompt template for analyzing tables"""
|
||||
return f"""Please analyze this database table:
|
||||
Table: {table}
|
||||
Schema:
|
||||
{get_schema()}
|
||||
|
||||
What insights can you provide about the structure and relationships?"""
|
||||
```
|
||||
* `simple_echo.py`: Basic tool, resource, and prompt.
|
||||
* `complex_inputs.py`: Using Pydantic models for tool inputs.
|
||||
* `mount_example.py`: Mounting multiple FastMCP servers.
|
||||
* `screenshot.py`: Tool returning an Image object.
|
||||
* `text_me.py`: Tool interacting with an external API.
|
||||
* `memory.py`: More complex example with database interaction.
|
||||
|
||||
## Contributing
|
||||
|
||||
Contributions make the open-source community vibrant! We welcome improvements and features.
|
||||
|
||||
<details>
|
||||
|
||||
<summary><h3>Open Developer Guide</h3></summary>
|
||||
|
||||
### Prerequisites
|
||||
#### Prerequisites
|
||||
|
||||
FastMCP requires Python 3.10+ and [uv](https://docs.astral.sh/uv/).
|
||||
* Python 3.10+
|
||||
* [uv](https://docs.astral.sh/uv/)
|
||||
|
||||
### Installation
|
||||
#### Setup
|
||||
|
||||
For development, we recommend installing FastMCP with development dependencies, which includes various utilities the maintainers find useful.
|
||||
1. Clone: `git clone https://github.com/jlowin/fastmcp.git && cd fastmcp`
|
||||
2. Install Env & Dependencies: `uv venv && uv sync --dev` (Activate the `.venv` after creation)
|
||||
|
||||
#### Testing
|
||||
|
||||
Run the test suite:
|
||||
```bash
|
||||
git clone https://github.com/jlowin/fastmcp.git
|
||||
cd fastmcp
|
||||
uv sync
|
||||
uv run pytest -vv
|
||||
```
|
||||
|
||||
### Testing
|
||||
#### Formatting & Linting
|
||||
|
||||
Please make sure to test any new functionality. Your tests should be simple and atomic and anticipate change rather than cement complex patterns.
|
||||
We use `ruff` via `pre-commit`.
|
||||
1. Install hooks: `pre-commit install`
|
||||
2. Run checks: `pre-commit run --all-files`
|
||||
|
||||
Run tests from the root directory:
|
||||
#### Pull Requests
|
||||
|
||||
1. Fork the repository.
|
||||
2. Create a feature branch.
|
||||
3. Make changes, commit, and push to your fork.
|
||||
4. Open a pull request against the `main` branch of `jlowin/fastmcp`.
|
||||
|
||||
```bash
|
||||
pytest -vv
|
||||
```
|
||||
Please open an issue or discussion for questions or suggestions!
|
||||
|
||||
### Formatting
|
||||
|
||||
FastMCP enforces a variety of required formats, which you can automatically enforce with pre-commit.
|
||||
|
||||
Install the pre-commit hooks:
|
||||
|
||||
```bash
|
||||
pre-commit install
|
||||
```
|
||||
|
||||
The hooks will now run on every commit (as well as on every PR). To run them manually:
|
||||
|
||||
```bash
|
||||
pre-commit run --all-files
|
||||
```
|
||||
|
||||
### Opening a Pull Request
|
||||
|
||||
Fork the repository and create a new branch:
|
||||
|
||||
```bash
|
||||
git checkout -b my-branch
|
||||
```
|
||||
|
||||
Make your changes and commit them:
|
||||
|
||||
|
||||
```bash
|
||||
git add . && git commit -m "My changes"
|
||||
```
|
||||
|
||||
Push your changes to your fork:
|
||||
|
||||
|
||||
```bash
|
||||
git push origin my-branch
|
||||
```
|
||||
|
||||
Feel free to reach out in a GitHub issue or discussion if you have any questions!
|
||||
|
||||
</details>
|
||||
</details>
|
||||
|
|
@ -6,7 +6,14 @@ from importlib.metadata import version
|
|||
from fastmcp.server.server import FastMCP
|
||||
from fastmcp.server.context import Context
|
||||
from fastmcp.client import Client
|
||||
from fastmcp.utilities.types import Image
|
||||
from . import client, settings
|
||||
|
||||
__version__ = version("fastmcp")
|
||||
__all__ = ["FastMCP", "Context", "client", "settings"]
|
||||
__all__ = [
|
||||
"FastMCP",
|
||||
"Context",
|
||||
"client",
|
||||
"settings",
|
||||
"Image",
|
||||
]
|
||||
|
|
|
|||
Loading…
Add table
Add a link
Reference in a new issue