From 3f1acbbcd01ef439b5743bdc09ec8bd6319ae184 Mon Sep 17 00:00:00 2001 From: Jeremiah Lowin <153965+jlowin@users.noreply.github.com> Date: Mon, 2 Jun 2025 17:48:52 -0400 Subject: [PATCH] Add claude desktop docs --- docs/clients/auth/bearer.mdx | 20 ++- docs/docs.json | 9 +- docs/integrations/anthropic.mdx | 15 +- docs/integrations/claude-desktop.mdx | 221 ++++++++++++++++++++++++++ docs/integrations/openai.mdx | 2 +- docs/{deployment => patterns}/cli.mdx | 27 ++-- 6 files changed, 261 insertions(+), 33 deletions(-) create mode 100644 docs/integrations/claude-desktop.mdx rename docs/{deployment => patterns}/cli.mdx (89%) diff --git a/docs/clients/auth/bearer.mdx b/docs/clients/auth/bearer.mdx index 68459ebf6..4ad8103fb 100644 --- a/docs/clients/auth/bearer.mdx +++ b/docs/clients/auth/bearer.mdx @@ -30,23 +30,25 @@ The most straightforward way to use a pre-existing Bearer token is to provide it If you're using a string token, do not include the `Bearer` prefix. FastMCP will add it for you. -```python {4} +```python {5} from fastmcp import Client async with Client( - "https://fastmcp.cloud/mcp", auth="" + "https://fastmcp.cloud/mcp", + auth="", ) as client: await client.ping() ``` You can also supply a Bearer token to a transport instance, such as `StreamableHttpTransport` or `SSETransport`: -```python {5} +```python {6} from fastmcp import Client from fastmcp.client.transports import StreamableHttpTransport transport = StreamableHttpTransport( - "http://fastmcp.cloud/mcp", auth="" + "http://fastmcp.cloud/mcp", + auth="", ) async with Client(transport) as client: @@ -57,12 +59,13 @@ async with Client(transport) as client: If you prefer to be more explicit and not rely on FastMCP to transform your string token, you can use the `BearerAuth` class yourself, which implements the `httpx.Auth` interface. -```python {5} +```python {6} from fastmcp import Client from fastmcp.client.auth import BearerAuth async with Client( - "https://fastmcp.cloud/mcp", auth=BearerAuth(token="") + "https://fastmcp.cloud/mcp", + auth=BearerAuth(token=""), ) as client: await client.ping() ``` @@ -71,11 +74,12 @@ async with Client( If the MCP server expects a custom header or token scheme, you can manually set the client's `headers` instead of using the `auth` parameter: -```python {4} +```python {5} from fastmcp import Client async with Client( - "https://fastmcp.cloud/mcp", headers={"X-API-Key": ""} + "https://fastmcp.cloud/mcp", + headers={"X-API-Key": ""}, ) as client: await client.ping() ``` diff --git a/docs/docs.json b/docs/docs.json index 2007456f5..e7c3a8942 100644 --- a/docs/docs.json +++ b/docs/docs.json @@ -71,8 +71,7 @@ "icon": "upload", "pages": [ "deployment/running-server", - "deployment/asgi", - "deployment/cli" + "deployment/asgi" ] } ] @@ -96,8 +95,9 @@ { "group": "Integrations", "pages": [ - "integrations/openai", "integrations/anthropic", + "integrations/claude-desktop", + "integrations/openai", "integrations/contrib" ] }, @@ -106,7 +106,8 @@ "pages": [ "patterns/decorating-methods", "patterns/http-requests", - "patterns/testing" + "patterns/testing", + "patterns/cli" ] } ] diff --git a/docs/integrations/anthropic.mdx b/docs/integrations/anthropic.mdx index f452a334c..b01f01ede 100644 --- a/docs/integrations/anthropic.mdx +++ b/docs/integrations/anthropic.mdx @@ -1,21 +1,20 @@ --- title: Anthropic sidebarTitle: Anthropic -description: Integrate FastMCP servers with the Anthropic Messages API +description: Access FastMCP servers from the Anthropic Messages API icon: message-smile --- import { VersionBadge } from "/snippets/version-badge.mdx" -Anthropic's Claude supports MCP servers through the MCP connector feature in the Messages API, allowing you to extend AI capabilities with custom tools from remote MCP servers. +Anthropic supports MCP servers through the [MCP connector](https://docs.anthropic.com/en/docs/agents-and-tools/mcp-connector) feature in the Messages API, allowing you to extend AI capabilities with custom tools from remote MCP servers. ## Messages API -Anthropic's [Messages API](https://docs.anthropic.com/en/api/messages) supports [MCP servers](https://docs.anthropic.com/en/docs/agents-and-tools/mcp-connector) as remote tool sources through the MCP connector feature. - +Anthropic's [Messages API](https://docs.anthropic.com/en/api/messages) supports MCP servers as remote tool sources. This tutorial will show you how to create a FastMCP server and deploy it to a public URL, then how to call it from the Messages API. -Currently, the MCP connector only accesses **tools** from MCP servers—it queries the `list_tools` endpoint and exposes those functions to Claude. Other MCP features like resources and prompts are not currently supported. +Currently, the MCP connector only accesses **tools** from MCP servers—it queries the `list_tools` endpoint and exposes those functions to Claude. Other MCP features like resources and prompts are not currently supported. You can read more about the MCP connector in the [Anthropic documentation](https://docs.anthropic.com/en/docs/agents-and-tools/mcp-connector). ### Create a Server @@ -67,9 +66,9 @@ To use the Messages API with MCP servers, you'll need to install the Anthropic P pip install anthropic ``` -Here is an example of how to call your server from Python. Note that you'll need to replace `https://your-server-url.com` with the actual URL of your server. In addition, we use `/sse` as the endpoint because we deployed an SSE server with the default path; you may need to use a different endpoint if you customized your server's deployment. +Here is an example of how to call your server from Python. Note that you'll need to replace `https://your-server-url.com` with the actual URL of your server. In addition, we use `/sse` as the endpoint because we deployed an SSE server with the default path; you may need to use a different endpoint if you customized your server's deployment. **At this time you must also include the `extra_headers` parameter with the `anthropic-beta` header.** -```python {4, 12-19} +```python {5, 13-22} import anthropic from rich import print @@ -191,7 +190,7 @@ Error code: 400 - { To authenticate the client, you can pass the token using the `authorization_token` parameter in your MCP server configuration: -```python {7, 17} +```python {8, 21} import anthropic from rich import print diff --git a/docs/integrations/claude-desktop.mdx b/docs/integrations/claude-desktop.mdx new file mode 100644 index 000000000..9212418f1 --- /dev/null +++ b/docs/integrations/claude-desktop.mdx @@ -0,0 +1,221 @@ +--- +title: Claude Desktop +sidebarTitle: Claude Desktop +description: Integrate FastMCP servers with Claude Desktop +icon: desktop +--- + + +Claude Desktop supports MCP servers through local STDIO connections, allowing you to extend Claude's capabilities with custom tools, resources, and prompts from your FastMCP servers. + + +This guide focuses specifically on using FastMCP servers with Claude Desktop. For general Claude Desktop MCP setup and official examples, see the [official Claude Desktop quickstart guide](https://modelcontextprotocol.io/quickstart/user). + + + +## Requirements + +Claude Desktop requires MCP servers to run locally using STDIO transport. This means your server will communicate with Claude through standard input/output rather than HTTP. + + +If you need to connect to remote servers, you can create a **proxy server** that runs locally via STDIO and forwards requests to remote HTTP servers. See the [Proxy Servers](#proxy-servers) section below. + + +## 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 + +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. + +```bash +fastmcp install 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 + +# Use explicit object name if your server has a different name +fastmcp install 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. + +#### Dependencies + +If your server has dependencies, include them with the `--with` flag: + +```bash +fastmcp install 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 + + +Claude Desktop 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. + + +If your server needs environment variables (like API keys), you must include them: + +```bash +fastmcp install 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 server.py --name "Weather Server" --env-file .env +``` + +- **`uv` must be installed and available in your system PATH**. Claude Desktop runs in its own isolated environment and needs `uv` to manage dependencies. +- **On macOS, it is recommended to install `uv` globally with Homebrew** so that Claude Desktop will detect it: `brew install uv`. Installing `uv` with other methods may not make it accessible to Claude Desktop. + + + +### Manual Configuration + +For more control over the configuration, you can manually edit Claude Desktop's configuration file. You can open the configuration file from Claude's developer settings, or find it in the following locations: +- **macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json` +- **Windows**: `%APPDATA%\Claude\claude_desktop_config.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, restart Claude Desktop completely. Look for the hammer icon (🔨) to confirm your server is loaded. + +#### 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" + ] + } + } +} +``` + + +- **`uv` must be installed and available in your system PATH**. Claude Desktop runs in its own isolated environment and needs `uv` to manage dependencies. +- **On macOS, it is recommended to install `uv` globally with Homebrew** so that Claude Desktop will detect it: `brew install uv`. Installing `uv` with other methods may not make it accessible to Claude Desktop. + + +#### 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" + } + } + } +} +``` + +Claude Desktop 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. + + + +## Remote Servers + + +Claude Desktop only supports local STDIO servers, but FastMCP can create a proxy server that forwards requests to a remote HTTP server. You can install the proxy server in Claude Desktop. + +Create a proxy server that connects to a remote HTTP server: + +```python proxy_server.py +from fastmcp import FastMCP + +# Create a proxy to a remote server +proxy = FastMCP.as_proxy( + "https://example.com/mcp/sse", + name="Remote Server Proxy" +) + +if __name__ == "__main__": + proxy.run() # Runs via STDIO for Claude Desktop +``` + +### Authentication + +For authenticated remote servers, create an authenticated client following the guidance in the [client auth documentation](/clients/auth/bearer) and pass it to the proxy: + +```python auth_proxy_server.py {7} +from fastmcp import FastMCP, Client +from fastmcp.client.auth import BearerAuth + +# Create authenticated client +client = Client( + "https://api.example.com/mcp/sse", + auth=BearerAuth(token="your-access-token") +) + +# Create proxy using the authenticated client +proxy = FastMCP.as_proxy(client, name="Authenticated Proxy") + +if __name__ == "__main__": + proxy.run() +``` + diff --git a/docs/integrations/openai.mdx b/docs/integrations/openai.mdx index 4830c6804..2db6fdbcd 100644 --- a/docs/integrations/openai.mdx +++ b/docs/integrations/openai.mdx @@ -1,7 +1,7 @@ --- title: OpenAI sidebarTitle: OpenAI -description: Integrate FastMCP servers with the OpenAI API +description: Access FastMCP servers from the OpenAI API icon: message-smile --- diff --git a/docs/deployment/cli.mdx b/docs/patterns/cli.mdx similarity index 89% rename from docs/deployment/cli.mdx rename to docs/patterns/cli.mdx index 2027c13bc..b46d928d4 100644 --- a/docs/deployment/cli.mdx +++ b/docs/patterns/cli.mdx @@ -148,8 +148,8 @@ Install a MCP server in the Claude desktop app. fastmcp install server.py ``` - Note that for security reasons, Claude runs every MCP server in a completely isolated environment. Therefore, all dependencies must be explicitly specified using the `--with` and/or `--with-editable` options (following `uv` conventions) or by attaching them to your server in code via the `dependencies` parameter. + - **`uv` must be installed and available in your system PATH**. Claude Desktop runs in its own isolated environment and needs `uv` to manage dependencies. - **On macOS, it is recommended to install `uv` globally with Homebrew** so that Claude Desktop will detect it: `brew install uv`. Installing `uv` with other methods may not make it accessible to Claude Desktop. @@ -159,21 +159,24 @@ Note that for security reasons, Claude runs every MCP server in a completely iso The `install` command currently only sets up servers for STDIO transport. When installed in the Claude desktop app, your server will be run using STDIO regardless of any transport configuration in your code. -#### Options +#### Server Specification -| Option | Flag | Description | -| ------ | ---- | ----------- | -| Server Name | `--name`, `-n` | Custom name for the server | -| Editable Package | `--with-editable`, `-e` | Directory containing pyproject.toml to install in editable mode | -| Additional Packages | `--with` | Additional packages to install (can be used multiple times) | -| Environment Variables | `--env-var`, `-v` | Environment variables in KEY=VALUE format (can be used multiple times) | -| Environment File | `--env-file`, `-f` | Load environment variables from a .env file | +The `install` command supports the same `file.py:object` notation as the `run` command: -**Example** +1. `server.py` - imports the module and looks for a FastMCP object named `mcp`, `server`, or `app`. Errors if no such object is found. +2. `server.py:custom_name` - imports and uses the specified server object + +**Examples** ```bash -# Install server with custom name, dependencies, and environment variables -fastmcp install server.py -n "My Analysis Server" -e . --with pandas --env-var API_KEY=12345 +# Auto-detects server object (looks for 'mcp', 'server', or 'app') +fastmcp install server.py + +# Uses specific server object +fastmcp install server.py:my_server + +# With custom name and dependencies +fastmcp install server.py:my_server -n "My Analysis Server" --with pandas ``` ### `version`