fastmcp 2.10.2__tar.gz → 2.10.3__tar.gz

{fastmcp-2.10.2 → fastmcp-2.10.3}/.github/ISSUE_TEMPLATE/bug.yml

@@ -48,9 +48,11 @@ body:
         To get this information, run the following command in your terminal and paste the output below:
 
         ```bash
-        fastmcp version
+        fastmcp version --copy
         ```
 
+        *Note: if you're using FastMCP < 2.10.3, run `fastmcp version` instead.*
+
         If there is other information that would be helpful, please include it as well.
       render: Text
     validations:

{fastmcp-2.10.2 → fastmcp-2.10.3}/.pre-commit-config.yaml

@@ -2,7 +2,7 @@ fail_fast: false
 
 repos:
   - repo: https://github.com/abravalheri/validate-pyproject
-    rev: v0.23
+    rev: v0.24.1
     hooks:
       - id: validate-pyproject
 
@@ -14,10 +14,10 @@ repos:
 
   - repo: https://github.com/astral-sh/ruff-pre-commit
     # Ruff version.
-    rev: v0.11.4
+    rev: v0.12.1
     hooks:
       # Run the linter.
-      - id: ruff
+      - id: ruff-check
         args: [--fix, --exit-non-zero-on-fix]
       # Run the formatter.
       - id: ruff-format

{fastmcp-2.10.2 → fastmcp-2.10.3}/PKG-INFO

@@ -1,7 +1,7 @@
 Metadata-Version: 2.4
 Name: fastmcp
-Version: 2.10.2
-Summary: The fast, Pythonic way to build MCP servers.
+Version: 2.10.3
+Summary: The fast, Pythonic way to build MCP servers and clients.
 Project-URL: Homepage, https://gofastmcp.com
 Project-URL: Repository, https://github.com/jlowin/fastmcp
 Project-URL: Documentation, https://gofastmcp.com
@@ -18,14 +18,15 @@ Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
 Classifier: Typing :: Typed
 Requires-Python: >=3.10
 Requires-Dist: authlib>=1.5.2
+Requires-Dist: cyclopts>=3.0.0
 Requires-Dist: exceptiongroup>=1.2.2
 Requires-Dist: httpx>=0.28.1
 Requires-Dist: mcp>=1.10.0
 Requires-Dist: openapi-pydantic>=0.5.1
 Requires-Dist: pydantic[email]>=2.11.7
+Requires-Dist: pyperclip>=1.9.0
 Requires-Dist: python-dotenv>=1.1.0
 Requires-Dist: rich>=13.9.4
-Requires-Dist: typer>=0.15.2
 Provides-Extra: websockets
 Requires-Dist: websockets>=15.0.1; extra == 'websockets'
 Description-Content-Type: text/markdown

fastmcp-2.10.3/docs/assets/favicon.svg

@@ -0,0 +1,3 @@
+<svg width="344" height="250" viewBox="0 0 344 250" fill="none" xmlns="http://www.w3.org/2000/svg">
+<path d="M317.594 60H178.438C158.407 60 140.309 71.9543 132.448 90.3779L123.789 111.3C129.321 110.442 134.957 109.998 140.653 109.998H297.593L272.593 169.999H140.653C123.17 169.999 100.093 177.499 88.0928 198.999L69.4229 242.662L66.5 249.726H0L77.2617 66.8311C94.5556 26.299 134.37 3.8525e-06 178.438 0H343.594L317.594 60Z" fill="black"/>
+</svg>

{fastmcp-2.10.2 → fastmcp-2.10.3}/docs/changelog.mdx

@@ -212,7 +212,7 @@ FastMCP 2.8.0 introduces powerful new ways to customize and control your MCP ser
 The highlight of this release is first-class [**Tool Transformation**](/patterns/tool-transformation), a new feature that lets you create enhanced variations of existing tools. You can now easily rename arguments, hide parameters, modify descriptions, and even wrap tools with custom validation or post-processing logic—all without rewriting the original code. This makes it easier than ever to adapt generic tools for specific LLM use cases or to simplify complex APIs. Huge thanks to [@strawgate](https://github.com/strawgate) for partnering on this, starting with [#591](https://github.com/jlowin/fastmcp/discussions/591) and [#599](https://github.com/jlowin/fastmcp/pull/599) and continuing offline.
 
 ### Component Control
-This release also gives you more granular control over which components are exposed to clients. With new [**tag-based filtering**](/servers/fastmcp#tag-based-filtering), you can selectively enable or disable tools, resources, and prompts based on tags, perfect for managing different environments or user permissions. Complementing this, every component now supports being [programmatically enabled or disabled](/servers/tools#disabling-tools), offering dynamic control over your server's capabilities.
+This release also gives you more granular control over which components are exposed to clients. With new [**tag-based filtering**](/servers/server#tag-based-filtering), you can selectively enable or disable tools, resources, and prompts based on tags, perfect for managing different environments or user permissions. Complementing this, every component now supports being [programmatically enabled or disabled](/servers/tools#disabling-tools), offering dynamic control over your server's capabilities.
 
 ### Tools-by-Default
 Finally, to improve compatibility with a wider range of LLM clients, this release changes the default behavior for OpenAPI integration: all API endpoints are now converted to `Tools` by default. This is a **breaking change** but pragmatically necessitated by the fact that the majority of MCP clients available today are, sadly, only compatible with MCP tools. Therefore, this change significantly simplifies the out-of-the-box experience and ensures your entire API is immediately accessible to any tool-using agent.

{fastmcp-2.10.2 → fastmcp-2.10.3}/docs/clients/transports.mdx

@@ -88,6 +88,18 @@ transport = StreamableHttpTransport(
 client = Client(transport)
 ```
 
+This can be written more concisely using the `BearerAuth` helper function:
+
+```python
+from fastmcp import Client
+from fastmcp.client.auth import BearerAuth
+
+client = Client(
+    "https://example.com/mcp",
+    auth=BearerAuth("your-token-here"),
+)
+```
+
 ### SSE (Server-Sent Events)
 
 <VersionBadge version="2.0.0" />
@@ -434,4 +446,4 @@ If your configuration has only a single server, the client will connect directly
 
 <Note>
 The MCPConfig format is an emerging standard for MCP server configuration and may change as the MCP ecosystem evolves. While FastMCP aims to maintain compatibility with future versions, be aware that field names or structure might change.
-</Note> 
+</Note>

{fastmcp-2.10.2 → fastmcp-2.10.3}/docs/community/showcase.mdx

@@ -56,4 +56,4 @@ We review submissions regularly and feature projects that provide value to the F
 
 ## Further Reading
 
-- [Contrib Modules](/integrations/contrib) - Community-contributed modules that are distributed with FastMCP itself
+- [Contrib Modules](/patterns/contrib) - Community-contributed modules that are distributed with FastMCP itself

{fastmcp-2.10.2 → fastmcp-2.10.3}/docs/css/style.css

@@ -1,6 +1,7 @@
 /* Code highlighting -- target only inline code elements, not code blocks */
 p code:not(pre code),
 table code:not(pre code),
+.prose code:not(pre code),
 li code:not(pre code),
 h1 code:not(pre code),
 h2 code:not(pre code),

{fastmcp-2.10.2 → fastmcp-2.10.3}/docs/docs.json

@@ -21,8 +21,8 @@
   },
   "description": "The fast, Pythonic way to build MCP servers and clients.",
   "favicon": {
-    "dark": "/assets/favicon.ico",
-    "light": "/assets/favicon.ico"
+    "dark": "/assets/favicon.svg",
+    "light": "/assets/favicon.svg"
   },
   "footer": {
     "socials": {
@@ -139,10 +139,11 @@
                   "integrations/chatgpt",
                   "integrations/claude-code",
                   "integrations/claude-desktop",
-                  "integrations/gemini",
-                  "integrations/openai",
+                  "integrations/cursor",
                   "integrations/eunomia-authorization",
-                  "integrations/contrib"
+                  "integrations/gemini",
+                  "integrations/mcp-json-configuration",
+                  "integrations/openai"
                 ]
               },
               {
@@ -152,7 +153,8 @@
                   "patterns/decorating-methods",
                   "patterns/http-requests",
                   "patterns/testing",
-                  "patterns/cli"
+                  "patterns/cli",
+                  "patterns/contrib"
                 ]
               },
               {

{fastmcp-2.10.2 → fastmcp-2.10.3}/docs/getting-started/quickstart.mdx

@@ -125,5 +125,5 @@ fastmcp run my_server.py:mcp
 Note that FastMCP *does not* require the `__main__` block in the server file, and will ignore it if it is present. Instead, it looks for the server object provided in the CLI command (here, `mcp`). If no server object is provided, `fastmcp run` will automatically search for servers called "mcp", "app", or "server" in the file.
 
 <Tip>
-We pointed our client at the server file, which is recognized as a Python MCP server and executed with `python my_server.py` by default. This executes the `__main__` block of the server file. There are other ways to run the server, which are described in the [server configuration](/servers/fastmcp#running-the-server) guide.
+We pointed our client at the server file, which is recognized as a Python MCP server and executed with `python my_server.py` by default. This executes the `__main__` block of the server file. There are other ways to run the server, which are described in the [server configuration](/servers/server#running-the-server) guide.
 </Tip>

{fastmcp-2.10.2 → fastmcp-2.10.3}/docs/integrations/anthropic.mdx

@@ -1,9 +1,8 @@
 ---
-title: Anthropic API + FastMCP
+title: Anthropic API 🤝 FastMCP
 sidebarTitle: Anthropic API
 description: Call FastMCP servers from the Anthropic API
-icon: message-smile
-tag: NEW
+icon: message-code
 ---
 
 import { VersionBadge } from "/snippets/version-badge.mdx"

{fastmcp-2.10.2 → fastmcp-2.10.3}/docs/integrations/chatgpt.mdx

@@ -1,5 +1,5 @@
 ---
-title: ChatGPT + FastMCP
+title: ChatGPT 🤝 FastMCP
 sidebarTitle: ChatGPT
 description: Connect FastMCP servers to ChatGPT Deep Research
 icon: message-smile

fastmcp-2.10.3/docs/integrations/claude-code.mdx

@@ -0,0 +1,133 @@
+---
+title: Claude Code 🤝 FastMCP
+sidebarTitle: Claude Code
+description: Install and use FastMCP servers in Claude Code
+icon: message-smile
+tag: NEW
+---
+
+import { VersionBadge } from "/snippets/version-badge.mdx"
+import { LocalFocusTip } from "/snippets/local-focus.mdx"
+
+<LocalFocusTip />
+
+Claude Code supports MCP servers through multiple transport methods including STDIO, SSE, and HTTP, allowing you to extend Claude's capabilities with custom tools, resources, and prompts from your FastMCP servers.
+
+## Requirements
+
+This integration uses STDIO transport to run your FastMCP server locally. For remote deployments, you can run your FastMCP server with HTTP or SSE transport and configure it directly using Claude Code's built-in MCP management commands.
+
+## Create a Server
+
+The examples in this guide will use the following simple dice-rolling server, saved as `server.py`.
+
+```python server.py
+import random
+from fastmcp import FastMCP
+
+mcp = FastMCP(name="Dice Roller")
+
+@mcp.tool
+def roll_dice(n_dice: int) -> list[int]:
+    """Roll `n_dice` 6-sided dice and return the results."""
+    return [random.randint(1, 6) for _ in range(n_dice)]
+
+if __name__ == "__main__":
+    mcp.run()
+```
+
+## Install the Server
+
+### FastMCP CLI
+<VersionBadge version="2.10.3" />
+
+The easiest way to install a FastMCP server in Claude Code is using the `fastmcp install claude-code` command. This automatically handles the configuration, dependency management, and calls Claude Code's built-in MCP management system.
+
+```bash
+fastmcp install claude-code server.py
+```
+
+The install command supports the same `file.py:object` notation as the `run` command. If no object is specified, it will automatically look for a FastMCP server object named `mcp`, `server`, or `app` in your file:
+
+```bash
+# These are equivalent if your server object is named 'mcp'
+fastmcp install claude-code server.py
+fastmcp install claude-code server.py:mcp
+
+# Use explicit object name if your server has a different name
+fastmcp install claude-code server.py:my_custom_server
+```
+
+The command will automatically configure the server with Claude Code's `claude mcp add` command.
+
+#### Dependencies
+
+If your server has dependencies, include them with the `--with` flag:
+
+```bash
+fastmcp install claude-code server.py --with pandas --with requests
+```
+
+Alternatively, you can specify dependencies directly in your server code:
+
+```python server.py
+from fastmcp import FastMCP
+
+mcp = FastMCP(
+    name="Dice Roller",
+    dependencies=["pandas", "requests"]
+)
+```
+
+#### Environment Variables
+
+If your server needs environment variables (like API keys), you must include them:
+
+```bash
+fastmcp install claude-code server.py --name "Weather Server" \
+  --env-var API_KEY=your-api-key \
+  --env-var DEBUG=true
+```
+
+Or load them from a `.env` file:
+
+```bash
+fastmcp install claude-code server.py --name "Weather Server" --env-file .env
+```
+
+<Warning>
+**Claude Code must be installed**. The integration looks for the Claude Code CLI at the default installation location (`~/.claude/local/claude`) and uses the `claude mcp add` command to register servers.
+</Warning>
+
+### Manual Configuration
+
+For more control over the configuration, you can manually use Claude Code's built-in MCP management commands:
+
+```bash
+# Add a server with custom configuration
+claude mcp add dice-roller -- uv run --with fastmcp fastmcp run server.py
+
+# Add with environment variables
+claude mcp add weather-server -e API_KEY=secret -e DEBUG=true -- uv run --with fastmcp fastmcp run server.py
+
+# Add with specific scope (local, user, or project)
+claude mcp add my-server --scope user -- uv run --with fastmcp fastmcp run server.py
+```
+
+## Using the Server
+
+Once your server is installed, you can start using your FastMCP server with Claude Code.
+
+Try asking Claude something like:
+
+> "Roll some dice for me"
+
+Claude will automatically detect your `roll_dice` tool and use it to fulfill your request, returning something like:
+
+> I'll roll some dice for you! Here are your results: [4, 2, 6]
+> 
+> You rolled three dice and got a 4, a 2, and a 6!
+
+Claude Code can now access all the tools, resources, and prompts you've defined in your FastMCP server. 
+
+If your server provides resources, you can reference them with `@` mentions using the format `@server:protocol://resource/path`. If your server provides prompts, you can use them as slash commands with `/mcp__servername__promptname`.

{fastmcp-2.10.2 → fastmcp-2.10.3}/docs/integrations/claude-desktop.mdx

@@ -1,10 +1,14 @@
 ---
-title: Claude Desktop + FastMCP
+title: Claude Desktop 🤝 FastMCP
 sidebarTitle: Claude Desktop
 description: Call FastMCP servers from Claude Desktop
 icon: message-smile
 ---
 
+import { VersionBadge } from "/snippets/version-badge.mdx"
+import { LocalFocusTip } from "/snippets/local-focus.mdx"
+
+<LocalFocusTip />
 
 Claude Desktop supports MCP servers through local STDIO connections and remote servers (beta), allowing you to extend Claude's capabilities with custom tools, resources, and prompts from your FastMCP servers.
 
@@ -47,22 +51,27 @@ if __name__ == "__main__":
 ## Install the Server
 
 ### FastMCP CLI
+<VersionBadge version="2.10.3" />
+
+The easiest way to install a FastMCP server in Claude Desktop is using the `fastmcp install claude-desktop` command. This automatically handles the configuration and dependency management.
 
-The easiest way to install a FastMCP server in Claude Desktop is using the `fastmcp install` command. This automatically handles the configuration and dependency management.
+<Tip>
+Prior to version 2.10.3, Claude Desktop could be managed by running `fastmcp install <path>` without specifying the client.
+</Tip>
 
 ```bash
-fastmcp install server.py
+fastmcp install claude-desktop server.py
 ```
 
 The install command supports the same `file.py:object` notation as the `run` command. If no object is specified, it will automatically look for a FastMCP server object named `mcp`, `server`, or `app` in your file:
 
 ```bash
 # These are equivalent if your server object is named 'mcp'
-fastmcp install server.py
-fastmcp install server.py:mcp
+fastmcp install claude-desktop server.py
+fastmcp install claude-desktop server.py:mcp
 
 # Use explicit object name if your server has a different name
-fastmcp install server.py:my_custom_server
+fastmcp install claude-desktop server.py:my_custom_server
 ```
 
 After installation, restart Claude Desktop completely. You should see a hammer icon (🔨) in the bottom left of the input box, indicating that MCP tools are available.
@@ -72,7 +81,7 @@ After installation, restart Claude Desktop completely. You should see a hammer i
 If your server has dependencies, include them with the `--with` flag:
 
 ```bash
-fastmcp install server.py --with pandas --with requests
+fastmcp install claude-desktop server.py --with pandas --with requests
 ```
 
 Alternatively, you can specify dependencies directly in your server code:
@@ -95,7 +104,7 @@ Claude Desktop runs servers in a completely isolated environment with no access
 If your server needs environment variables (like API keys), you must include them:
 
 ```bash
-fastmcp install server.py --name "Weather Server" \
+fastmcp install claude-desktop server.py --name "Weather Server" \
   --env-var API_KEY=your-api-key \
   --env-var DEBUG=true
 ```
@@ -103,7 +112,7 @@ fastmcp install server.py --name "Weather Server" \
 Or load them from a `.env` file:
 
 ```bash
-fastmcp install server.py --name "Weather Server" --env-file .env
+fastmcp install claude-desktop server.py --name "Weather Server" --env-file .env
 ```
 <Warning>
 - **`uv` must be installed and available in your system PATH**. Claude Desktop runs in its own isolated environment and needs `uv` to manage dependencies.

fastmcp-2.10.3/docs/integrations/cursor.mdx

@@ -0,0 +1,208 @@
+---
+title: Cursor 🤝 FastMCP
+sidebarTitle: Cursor
+description: Install and use FastMCP servers in Cursor
+icon: message-smile
+tag: NEW
+---
+
+import { VersionBadge } from "/snippets/version-badge.mdx"
+import { LocalFocusTip } from "/snippets/local-focus.mdx"
+
+<LocalFocusTip />
+
+Cursor supports MCP servers through multiple transport methods including STDIO, SSE, and Streamable HTTP, allowing you to extend Cursor's AI assistant with custom tools, resources, and prompts from your FastMCP servers.
+
+## Requirements
+
+This integration uses STDIO transport to run your FastMCP server locally. For remote deployments, you can run your FastMCP server with HTTP or SSE transport and configure it directly in Cursor's settings.
+
+## Create a Server
+
+The examples in this guide will use the following simple dice-rolling server, saved as `server.py`.
+
+```python server.py
+import random
+from fastmcp import FastMCP
+
+mcp = FastMCP(name="Dice Roller")
+
+@mcp.tool
+def roll_dice(n_dice: int) -> list[int]:
+    """Roll `n_dice` 6-sided dice and return the results."""
+    return [random.randint(1, 6) for _ in range(n_dice)]
+
+if __name__ == "__main__":
+    mcp.run()
+```
+
+## Install the Server
+
+### FastMCP CLI
+<VersionBadge version="2.10.3" />
+
+The easiest way to install a FastMCP server in Cursor is using the `fastmcp install cursor` command. This automatically handles the configuration, dependency management, and opens Cursor with a deeplink to install the server.
+
+```bash
+fastmcp install cursor server.py
+```
+
+The install command supports the same `file.py:object` notation as the `run` command. If no object is specified, it will automatically look for a FastMCP server object named `mcp`, `server`, or `app` in your file:
+
+```bash
+# These are equivalent if your server object is named 'mcp'
+fastmcp install cursor server.py
+fastmcp install cursor server.py:mcp
+
+# Use explicit object name if your server has a different name
+fastmcp install cursor server.py:my_custom_server
+```
+
+After running the command, Cursor will open automatically and prompt you to install the server. The command will be `uv`, which is expected as this is a Python STDIO server. Click "Install" to confirm:
+
+![Cursor install prompt](./cursor-install-mcp.png)
+
+#### Dependencies
+
+If your server has dependencies, include them with the `--with` flag:
+
+```bash
+fastmcp install cursor server.py --with pandas --with requests
+```
+
+Alternatively, you can specify dependencies directly in your server code:
+
+```python server.py
+from fastmcp import FastMCP
+
+mcp = FastMCP(
+    name="Dice Roller",
+    dependencies=["pandas", "requests"]
+)
+```
+
+#### Environment Variables
+
+<Warning>
+Cursor runs servers in a completely isolated environment with no access to your shell environment or locally installed applications. You must explicitly pass any environment variables your server needs.
+</Warning>
+
+If your server needs environment variables (like API keys), you must include them:
+
+```bash
+fastmcp install cursor server.py --name "Weather Server" \
+  --env-var API_KEY=your-api-key \
+  --env-var DEBUG=true
+```
+
+Or load them from a `.env` file:
+
+```bash
+fastmcp install cursor server.py --name "Weather Server" --env-file .env
+```
+
+<Warning>
+**`uv` must be installed and available in your system PATH**. Cursor runs in its own isolated environment and needs `uv` to manage dependencies.
+</Warning>
+
+### Generate MCP JSON
+
+<Note>
+**Use the first-class integration above for the best experience.** The MCP JSON generation is useful for advanced use cases, manual configuration, or integration with other tools.
+</Note>
+
+You can generate MCP JSON configuration for manual use:
+
+```bash
+# Generate configuration and output to stdout
+fastmcp install mcp-json server.py --name "Dice Roller" --with pandas
+
+# Copy configuration to clipboard for easy pasting
+fastmcp install mcp-json server.py --name "Dice Roller" --copy
+```
+
+This generates the standard `mcpServers` configuration format that can be used with any MCP-compatible client.
+
+### Manual Configuration
+
+For more control over the configuration, you can manually edit Cursor's configuration file. The configuration file is located at:
+- **All platforms**: `~/.cursor/mcp.json`
+
+The configuration file is a JSON object with a `mcpServers` key, which contains the configuration for each MCP server.
+
+```json
+{
+  "mcpServers": {
+    "dice-roller": {
+      "command": "python",
+      "args": ["path/to/your/server.py"]
+    }
+  }
+}
+```
+
+After updating the configuration file, your server should be available in Cursor.
+
+#### Dependencies
+
+If your server has dependencies, you can use `uv` or another package manager to set up the environment.
+
+```json
+{
+  "mcpServers": {
+    "dice-roller": {
+      "command": "uv",
+      "args": [
+        "run",
+        "--with", "pandas",
+        "--with", "requests", 
+        "python",
+        "path/to/your/server.py"
+      ]
+    }
+  }
+}
+```
+
+<Warning>
+**`uv` must be installed and available in your system PATH**. Cursor runs in its own isolated environment and needs `uv` to manage dependencies.
+</Warning>
+
+#### Environment Variables
+
+You can also specify environment variables in the configuration:
+
+```json
+{
+  "mcpServers": {
+    "weather-server": {
+      "command": "python",
+      "args": ["path/to/weather_server.py"],
+      "env": {
+        "API_KEY": "your-api-key",
+        "DEBUG": "true"
+      }
+    }
+  }
+}
+```
+
+<Warning>
+Cursor runs servers in a completely isolated environment with no access to your shell environment or locally installed applications. You must explicitly pass any environment variables your server needs.
+</Warning>
+
+## Using the Server
+
+Once your server is installed, you can start using your FastMCP server with Cursor's AI assistant.
+
+Try asking Cursor something like:
+
+> "Roll some dice for me"
+
+Cursor will automatically detect your `roll_dice` tool and use it to fulfill your request, returning something like:
+
+> 🎲 Here are your dice rolls: 4, 6, 4
+> 
+> You rolled 3 dice with a total of 14! The 6 was a nice high roll there!
+
+The AI assistant can now access all the tools, resources, and prompts you've defined in your FastMCP server.

{fastmcp-2.10.2 → fastmcp-2.10.3}/docs/integrations/eunomia-authorization.mdx

@@ -1,8 +1,8 @@
 ---
-title: Eunomia Authorization + FastMCP
-sidebarTitle: Eunomia Authorization
+title: Eunomia Authorization 🤝 FastMCP
+sidebarTitle: Eunomia Auth
 description: Add policy-based authorization to your FastMCP servers
-icon: layer-group
+icon: shield-check
 tag: NEW
 ---
 

{fastmcp-2.10.2 → fastmcp-2.10.3}/docs/integrations/gemini.mdx

@@ -1,9 +1,8 @@
 ---
-title: Gemini SDK + FastMCP
+title: Gemini SDK 🤝 FastMCP
 sidebarTitle: Gemini SDK
 description: Call FastMCP servers from the Google Gemini SDK
-icon: message-smile
-tag: NEW
+icon: message-code
 ---
 
 import { VersionBadge } from "/snippets/version-badge.mdx"