1
# FastMCP
2

3
The fast, Pythonic way to build MCP servers and clients. FastMCP is a comprehensive framework for building Model Context Protocol (MCP) servers and clients with minimal boilerplate code, providing a clean, Pythonic API for creating tools, exposing resources, defining prompts, and connecting components in the MCP ecosystem.
4

5
## Package Information
6

7
- **Package Name**: fastmcp
8
- **Language**: Python
9
- **Installation**: `pip install fastmcp`
10
- **Python Requirements**: >=3.10
11

12
## Core Imports
13

14
```python
15
from fastmcp import FastMCP, Context, Client
16
```
17

18
## Basic Usage
19

20
### Creating a Simple MCP Server
21

22
```python
23
from fastmcp import FastMCP
24

25
# Create a server instance
26
mcp = FastMCP("Demo Server")
27

28
@mcp.tool
29
def add(a: int, b: int) -> int:
30
    """Add two numbers."""
31
    return a + b
32

33
@mcp.resource("config://version")
34
def get_version():
35
    """Get server version."""
36
    return "1.0.0"
37

38
@mcp.prompt
39
def summarize_request(text: str) -> str:
40
    """Generate a prompt asking for a summary."""
41
    return f"Please summarize the following text:\n\n{text}"
42

43
if __name__ == "__main__":
44
    mcp.run()  # Run with stdio transport
45
```
46

47
### Creating a Client
48

49
```python
50
from fastmcp import Client
51

52
async def main():
53
    # Connect to a server via stdio
54
    async with Client("server.py") as client:
55
        # List available tools
56
        tools = await client.list_tools()
57
        
58
        # Call a tool
59
        result = await client.call_tool("add", {"a": 5, "b": 3})
60
        print(result.text)
61
        
62
        # Read a resource
63
        resource = await client.read_resource("config://version")
64
        print(resource.content)
65
```
66

67
## Architecture
68

69
FastMCP is built around several core components that work together to provide a complete MCP framework:
70

71
- **FastMCP Server**: The main server class that manages tools, resources, prompts, and handles MCP protocol communication
72
- **Context**: Execution context providing capabilities like logging, LLM sampling, and HTTP requests to tools/resources/prompts
73
- **Client**: Full-featured client supporting multiple transports and authentication methods
74
- **Component System**: Modular architecture for tools, resources, and prompts with both decorator and class-based approaches
75
- **Transport Layer**: Multiple transport protocols (stdio, HTTP, SSE, WebSocket) for flexible deployment
76
- **Authentication**: Comprehensive auth system supporting OAuth, JWT, Bearer tokens, and custom providers
77
- **Middleware**: Extensible middleware system for request/response processing
78

79
## Capabilities
80

81
### Server Implementation
82

83
Core server functionality for creating MCP servers with decorators, managing components, and handling protocol communication.
84

85
```python { .api }
86
class FastMCP:
87
    def __init__(
88
        self,
89
        name: str,
90
        version: str = "0.1.0",
91
        instructions: str | None = None,
92
        auth_provider: AuthProvider | None = None,
93
        middlewares: list[Middleware] | None = None,
94
        settings: Settings | None = None
95
    ): ...
96
    
97
    def tool(self, func: Callable | None = None, *, name: str | None = None) -> Callable: ...
98
    def resource(self, uri: str) -> Callable: ...
99
    def prompt(self, func: Callable | None = None, *, name: str | None = None) -> Callable: ...
100
    def run(
101
        self,
102
        transport: Literal["stdio", "sse", "http"] = "stdio",
103
        host: str = "127.0.0.1",
104
        port: int = 8000,
105
        **kwargs
106
    ) -> None: ...
107
```
108

109
[Server Implementation](./server.md)
110

111
### Client Library
112

113
Full-featured MCP client supporting multiple transports, authentication, and advanced features like LLM sampling.
114

115
```python { .api }
116
class Client:
117
    def __init__(
118
        self,
119
        server_or_config: str | FastMCP | dict,
120
        transport: ClientTransport | None = None,
121
        auth: BearerAuth | OAuth | None = None,
122
        sampling_handler: SamplingHandler | None = None,
123
        elicitation_handler: ElicitationHandler | None = None
124
    ): ...
125
    
126
    async def list_tools(self) -> list: ...
127
    async def call_tool(self, name: str, arguments: dict | None = None): ...
128
    async def list_resources(self) -> list: ...
129
    async def read_resource(self, uri: str): ...
130
    async def list_prompts(self) -> list: ...
131
    async def get_prompt(self, name: str, arguments: dict | None = None): ...
132
```
133

134
[Client Library](./client.md)
135

136
### Tools System
137

138
Tools allow LLMs to perform actions by executing Python functions, with automatic schema generation and flexible return types.
139

140
```python { .api }
141
class Tool:
142
    def __init__(
143
        self,
144
        name: str,
145
        description: str,
146
        func: Callable,
147
        schema: dict | None = None
148
    ): ...
149

150
class FunctionTool(Tool): ...
151

152
class ToolManager:
153
    def add_tool(self, tool: Tool) -> None: ...
154
    def remove_tool(self, name: str) -> None: ...
155
    def get_tool(self, name: str) -> Tool | None: ...
156
```
157

158
[Tools System](./tools.md)
159

160
### Resources System
161

162
Resources expose read-only data sources with support for static resources and dynamic templates with URI parameters.
163

164
```python { .api }
165
class Resource:
166
    def __init__(
167
        self,
168
        uri: str,
169
        name: str,
170
        description: str,
171
        mime_type: str | None = None
172
    ): ...
173

174
class ResourceTemplate:
175
    def __init__(
176
        self,
177
        uri_template: str,
178
        name: str,
179
        description: str,
180
        mime_type: str | None = None
181
    ): ...
182

183
class ResourceManager:
184
    def add_resource(self, resource: Resource) -> None: ...
185
    def add_template(self, template: ResourceTemplate) -> None: ...
186
```
187

188
[Resources System](./resources.md)
189

190
### Prompts System
191

192
Prompts define reusable message templates to guide LLM interactions with parameter support and message formatting.
193

194
```python { .api }
195
class Prompt:
196
    def __init__(
197
        self,
198
        name: str,
199
        description: str,
200
        func: Callable,
201
        schema: dict | None = None
202
    ): ...
203

204
class PromptManager:
205
    def add_prompt(self, prompt: Prompt) -> None: ...
206
    def get_prompt(self, name: str) -> Prompt | None: ...
207

208
def Message(
209
    role: Literal["user", "assistant", "system"],
210
    content: str | dict,
211
    name: str | None = None
212
): ...
213
```
214

215
[Prompts System](./prompts.md)
216

217
### Context and Dependencies
218

219
Execution context providing capabilities like logging, LLM sampling, HTTP requests, and resource access to tools/resources/prompts.
220

221
```python { .api }
222
class Context:
223
    async def info(self, message: str) -> None: ...
224
    async def error(self, message: str) -> None: ...
225
    async def debug(self, message: str) -> None: ...
226
    async def sample(
227
        self,
228
        messages: list[dict],
229
        params: dict | None = None
230
    ): ...
231
    async def read_resource(self, uri: str): ...
232
    async def http_request(
233
        self,
234
        method: str,
235
        url: str,
236
        headers: dict | None = None,
237
        data: Any | None = None
238
    ): ...
239
    async def report_progress(self, progress: int, total: int | None = None) -> None: ...
240
```
241

242
[Context and Dependencies](./context.md)
243

244
### Transport Layer
245

246
Multiple transport protocols for flexible server deployment and client connections.
247

248
```python { .api }
249
class ClientTransport: ...
250
class StdioTransport(ClientTransport): ...
251
class SSETransport(ClientTransport): ...
252
class StreamableHttpTransport(ClientTransport): ...
253
class WSTransport(ClientTransport): ...
254
class FastMCPTransport(ClientTransport): ...
255
```
256

257
[Transport Layer](./transports.md)
258

259
### Authentication
260

261
Comprehensive authentication system supporting multiple providers and tokens for secure server and client connections.
262

263
```python { .api }
264
class AuthProvider: ...
265
class OAuthProvider(AuthProvider): ...
266
class JWTVerifier(AuthProvider): ...
267
class TokenVerifier(AuthProvider): ...
268
class StaticTokenVerifier(AuthProvider): ...
269
class RemoteAuthProvider(AuthProvider): ...
270

271
class BearerAuth: ...
272
class OAuth: ...
273
class AccessToken: ...
274
```
275

276
[Authentication](./authentication.md)
277

278
### Utilities and Types
279

280
Helper classes and utility functions for enhanced functionality and type support.
281

282
```python { .api }
283
class Image:
284
    def __init__(
285
        self,
286
        data: bytes | str,
287
        mime_type: str = "image/png"
288
    ): ...
289

290
class Audio:
291
    def __init__(
292
        self,
293
        data: bytes | str,
294
        mime_type: str = "audio/wav"
295
    ): ...
296

297
class File:
298
    def __init__(
299
        self,
300
        data: bytes | str,
301
        name: str,
302
        mime_type: str | None = None
303
    ): ...
304

305
class Settings: ...
306
class MCPConfig: ...
307
```
308

309
[Utilities and Types](./utilities.md)
310

311
## Types
312

313
```python { .api }
314
# Core types
315
from typing import Callable, Any, Literal
316
from pydantic import BaseModel
317

318
class FastMCPBaseModel(BaseModel): ...
319

320
# Function signatures for decorators
321
ToolFunction = Callable[..., Any]
322
ResourceFunction = Callable[..., str | bytes | dict]
323
PromptFunction = Callable[..., str | list[dict]]
324

325
# Transport types
326
TransportType = Literal["stdio", "sse", "http", "ws"]
327

328
# Authentication types
329
SamplingHandler = Callable[[list[dict]], Any]
330
ElicitationHandler = Callable[[dict], Any]
331

332
# Component types
333
class MCPMixin: ...
334
ComponentFn = Callable[..., Any]
335
```