ceos/fastmcp
1
0
Fork 0
mirror of https://github.com/PrefectHQ/fastmcp.git synced 2026-08-09 15:19:10 +02:00
Code Issues Projects Releases Packages Wiki Activity

Support dependencies

Browse source
This commit is contained in:
Jeremiah Lowin 2024-12-01 20:55:16 -05:00
commit 709b48bbb7
6 changed files with 244 additions and 130 deletions
Download patch file Download diff file Expand all files Collapse all files

156
README.md
View file

@ -62,15 +62,20 @@ FastMCP handles all the complex protocol details and server management, so you c
- [Prompts](#prompts)
- [Images](#images)
- [Context](#context)
- [Deployment](#deployment)
- [Development](#development)
- [Environment Variables](#environment-variables)
- [Claude Desktop](#claude-desktop)
- [Environment Variables](#environment-variables-1)
- [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)
## Installation
@ -154,8 +159,10 @@ mcp = FastMCP("My App")
# Configure host/port for HTTP transport (optional)
mcp = FastMCP("My App", host="localhost", port=8000)
# Specify dependencies for deployment and development
mcp = FastMCP("My App", dependencies=["pandas", "numpy"])
```
*Note: All of the following code examples assume you've created a FastMCP server instance called `mcp`, as shown above.*
### Resources
@ -284,84 +291,101 @@ The Context object provides:
- Resource access through `read_resource()`
- Request metadata via `request_id` and `client_id`
## Deployment
## Running Your Server
The FastMCP CLI helps you develop and deploy MCP servers.
There are three main ways to use your FastMCP server, each suited for different stages of development:
Note that for all deployment commands, you are expected to provide the fully qualified path to your server object. For example, if you have a file `server.py` that contains a FastMCP server named `my_server`, you would provide `path/to/server.py:my_server`.
### Development Mode (Recommended for Building & Testing)
If your server variable has one of the standard names (`mcp`, `server`, or `app`), you can omit the server name from the path and just provide the file: `path/to/server.py`.
The fastest way to test and debug your server is with the MCP Inspector:
### Development
Test and debug your server with the MCP Inspector:
```bash
# Provide the fully qualified path to your server
fastmcp dev server.py:my_mcp_server
# Or just the file if your server is named 'mcp', 'server', or 'app'
fastmcp dev server.py
```
Your server is run in an isolated environment, so you'll need to indicate any dependencies with the `--with` flag. FastMCP is automatically included. If you are working on a uv project, you can use the `--with-editable` flag to mount your current directory:
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
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:
```bash
# With additional packages
fastmcp dev server.py --with pandas --with numpy
# Using your project's dependencies and up-to-date code
fastmcp dev server.py --with-editable .
```
#### Environment Variables
The MCP Inspector runs servers in an isolated environment. Environment variables must be set through the Inspector UI and are not inherited from your system. The Inspector does not currently support setting environment variables via command line (see [Issue #94](https://github.com/modelcontextprotocol/inspector/issues/94)).
### Claude Desktop
Install your server in Claude Desktop:
```bash
# Basic usage (name is taken from your FastMCP instance)
fastmcp install server.py
# With a custom name
fastmcp install server.py --name "My Server"
# With dependencies
fastmcp install server.py --with pandas --with numpy
```
The server name in Claude will be:
1. The `--name` parameter if provided
2. The `name` from your FastMCP instance
3. The filename if the server can't be imported
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
```
#### Environment Variables
### Direct Execution (For Advanced Use Cases)
Claude Desktop runs servers in an isolated environment. Environment variables from your system are NOT automatically available to the server - you must explicitly provide them during installation:
For advanced scenarios like custom deployments or running without Claude, you can execute your server directly:
```bash
# Single env var
fastmcp install server.py -e API_KEY=abc123
```python
from fastmcp import FastMCP
# Multiple env vars
fastmcp install server.py -e API_KEY=abc123 -e OTHER_VAR=value
mcp = FastMCP("My App")
# Load from .env file
fastmcp install server.py -f .env
if __name__ == "__main__":
mcp.run()
```
Environment variables persist across reinstalls and are only updated when new values are provided:
Run it with:
```bash
# Using the FastMCP CLI
fastmcp run server.py
# Or with Python/uv directly
python server.py
uv run python server.py
```
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.
Choose this method when you need:
- Custom deployment configurations
- Integration with other services
- Direct control over the server lifecycle
### 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`:
```bash
# First install
fastmcp install server.py -e FOO=bar -e BAZ=123
# Using a standard name
fastmcp run server.py
# Second install - FOO and BAZ are preserved
fastmcp install server.py -e NEW=value
# Third install - FOO gets new value, others preserved
fastmcp install server.py -e FOO=newvalue
# Using a custom name
fastmcp run server.py:my_custom_server
```
## Examples
@ -437,11 +461,11 @@ What insights can you provide about the structure and relationships?"""
<summary><h3>Open Developer Guide</h3></summary>
#### Prerequisites
### Prerequisites
FastMCP requires Python 3.10+ and [uv](https://docs.astral.sh/uv/).
#### Installation
### Installation
Create a fork of this repository, then clone it:
@ -460,7 +484,7 @@ uv sync --frozen --all-extras --dev
#### Testing
### Testing
Please make sure to test any new functionality. Your tests should be simple and atomic and anticipate change rather than cement complex patterns.
@ -471,7 +495,7 @@ Run tests from the root directory:
pytest -vv
```
#### Formatting
### Formatting
FastMCP enforces a variety of required formats, which you can automatically enforce with pre-commit.
@ -487,7 +511,7 @@ The hooks will now run on every commit (as well as on every PR). To run them man
pre-commit run --all-files
```
#### Opening a Pull Request
### Opening a Pull Request
Fork the repository and create a new branch:

16
examples/screenshot.py
View file

@ -1,7 +1,3 @@
# /// script
# dependencies = ["fastmcp", "pyautogui", "Pillow"]
# ///
"""
FastMCP Screenshot Example
@ -9,20 +5,24 @@ Give Claude a tool to capture and view screenshots.
"""
import io
from fastmcp import FastMCP, Image
# Create server
mcp = FastMCP("Screenshot Demo")
mcp = FastMCP("Screenshot Demo", dependencies=["pyautogui", "Pillow"])
@mcp.tool()
def take_screenshot() -> Image:
"""Take a screenshot of the user's screen and return it as an image"""
"""
Take a screenshot of the user's screen and return it as an image. Use
this tool anytime the user wants you to look at something they're doing.
"""
import pyautogui
screenshot = pyautogui.screenshot()
buffer = io.BytesIO()
# if the file exceeds ~1MB, it will be rejected by Claude
screenshot = pyautogui.screenshot()
screenshot.convert("RGB").save(buffer, format="JPEG", quality=60, optimize=True)
return Image(data=buffer.getvalue(), format="jpeg")

16
src/fastmcp/cli/claude.py
View file

@ -68,16 +68,20 @@ def update_claude_config(
env_vars = existing_env
# Build uv run command
args = ["run", "--with", "fastmcp"]
args = ["run"]
# Collect all packages in a set to deduplicate
packages = {"fastmcp"}
if with_packages:
packages.update(pkg for pkg in with_packages if pkg)
# Add all packages with --with
for pkg in sorted(packages):
args.extend(["--with", pkg])
if with_editable:
args.extend(["--with-editable", str(with_editable)])
if with_packages:
for pkg in with_packages:
if pkg:
args.extend(["--with", pkg])
# Convert file path to absolute before adding to command
# Split off any :object suffix first
if ":" in file_spec:

27
src/fastmcp/cli/cli.py
View file

@ -193,6 +193,11 @@ def dev(
)
try:
# Import server to get dependencies
server = _import_server(file, server_object)
if hasattr(server, "dependencies"):
with_packages = list(set(with_packages + server.dependencies))
uv_cmd = _build_uv_command(file_spec, with_editable, with_packages)
# Run the MCP Inspector command
process = subprocess.run(
@ -232,23 +237,16 @@ def run(
help="Transport protocol to use (stdio or sse)",
),
] = None,
with_editable: Annotated[
Optional[Path],
typer.Option(
"--with-editable",
"-e",
help="Directory containing pyproject.toml to install in editable mode",
exists=True,
file_okay=False,
resolve_path=True,
),
] = None,
) -> None:
"""Run a FastMCP server.
The server can be specified in two ways:
1. Module approach: server.py - runs the module directly, expecting a server.run() call
2. Import approach: server.py:app - imports and runs the specified server object
Note: This command runs the server directly. You are responsible for ensuring
all dependencies are available. For dependency management, use fastmcp install
or fastmcp dev instead.
"""
file, server_object = _parse_file_path(file_spec)
@ -258,7 +256,6 @@ def run(
"file": str(file),
"server_object": server_object,
"transport": transport,
"with_editable": str(with_editable) if with_editable else None,
},
)
@ -361,6 +358,7 @@ def install(
# Try to import server to get its name, but fall back to file name if dependencies missing
name = server_name
server = None
if not name:
try:
server = _import_server(file, server_object)
@ -372,6 +370,11 @@ def install(
)
name = file.stem
# Get server dependencies if available
server_dependencies = getattr(server, "dependencies", []) if server else []
if server_dependencies:
with_packages = list(set(with_packages + server_dependencies))
# Process environment variables if provided
env_dict: Optional[Dict[str, str]] = None
if env_file or env_vars:

7
src/fastmcp/server.py
View file

@ -9,6 +9,7 @@ from itertools import chain
from typing import Any, Callable, Dict, Literal, Sequence
import pydantic_core
from pydantic import Field
import uvicorn
from mcp.server import Server as MCPServer
from mcp.server.sse import SseServerTransport
@ -76,6 +77,11 @@ class Settings(BaseSettings):
# prompt settings
warn_on_duplicate_prompts: bool = True
dependencies: list[str] = Field(
default_factory=list,
description="List of dependencies to install in the server environment",
)
class FastMCP:
def __init__(self, name: str | None = None, **settings: Any):
@ -90,6 +96,7 @@ class FastMCP:
self._prompt_manager = PromptManager(
warn_on_duplicate_prompts=self.settings.warn_on_duplicate_prompts
)
self.dependencies = self.settings.dependencies
# Set up MCP protocol handlers
self._setup_handlers()

160
tests/test_cli.py
View file

@ -1,7 +1,7 @@
"""Tests for the FastMCP CLI."""
import json
from unittest.mock import Mock, patch
from unittest.mock import patch
import pytest
from typer.testing import CliRunner
@ -19,11 +19,13 @@ def mock_config(tmp_path):
@pytest.fixture
def mock_server_file(tmp_path):
"""Create a mock server file."""
def server_file(tmp_path):
"""Create a server file."""
server_file = tmp_path / "server.py"
server_file.write_text(
"from fastmcp import Server\n" "server = Server(name='test')\n"
"""from fastmcp import FastMCP
mcp = FastMCP("test")
"""
)
return server_file
@ -67,22 +69,16 @@ def test_parse_env_var():
),
],
)
def test_install_with_env_vars(mock_config, mock_server_file, args, expected_env):
def test_install_with_env_vars(mock_config, server_file, args, expected_env):
"""Test installing with environment variables."""
runner = CliRunner()
with (
patch("fastmcp.cli.claude.get_claude_config_path") as mock_config_path,
patch("fastmcp.cli.cli._import_server") as mock_import,
):
with patch("fastmcp.cli.claude.get_claude_config_path") as mock_config_path:
mock_config_path.return_value = mock_config.parent
mock_server = Mock()
mock_server.name = "test" # Set name as an attribute
mock_import.return_value = mock_server
result = runner.invoke(
app,
["install", str(mock_server_file)] + args,
["install", str(server_file)] + args,
)
assert result.exit_code == 0
@ -95,22 +91,16 @@ def test_install_with_env_vars(mock_config, mock_server_file, args, expected_env
assert server["env"] == expected_env
def test_install_with_env_file(mock_config, mock_server_file, mock_env_file):
def test_install_with_env_file(mock_config, server_file, mock_env_file):
"""Test installing with environment variables from a file."""
runner = CliRunner()
with (
patch("fastmcp.cli.claude.get_claude_config_path") as mock_config_path,
patch("fastmcp.cli.cli._import_server") as mock_import,
):
with patch("fastmcp.cli.claude.get_claude_config_path") as mock_config_path:
mock_config_path.return_value = mock_config.parent
mock_server = Mock()
mock_server.name = "test" # Set name as an attribute
mock_import.return_value = mock_server
result = runner.invoke(
app,
["install", str(mock_server_file), "--env-file", str(mock_env_file)],
["install", str(server_file), "--env-file", str(mock_env_file)],
)
assert result.exit_code == 0
@ -123,7 +113,7 @@ def test_install_with_env_file(mock_config, mock_server_file, mock_env_file):
assert server["env"] == {"FOO": "bar", "BAZ": "123"}
def test_install_preserves_existing_env_vars(mock_config, mock_server_file):
def test_install_preserves_existing_env_vars(mock_config, server_file):
"""Test that installing preserves existing environment variables."""
# Set up initial config with env vars
config = {
@ -136,7 +126,7 @@ def test_install_preserves_existing_env_vars(mock_config, mock_server_file):
"fastmcp",
"fastmcp",
"run",
str(mock_server_file),
str(server_file),
],
"env": {"FOO": "bar", "BAZ": "123"},
}
@ -146,19 +136,13 @@ def test_install_preserves_existing_env_vars(mock_config, mock_server_file):
runner = CliRunner()
with (
patch("fastmcp.cli.claude.get_claude_config_path") as mock_config_path,
patch("fastmcp.cli.cli._import_server") as mock_import,
):
with patch("fastmcp.cli.claude.get_claude_config_path") as mock_config_path:
mock_config_path.return_value = mock_config.parent
mock_server = Mock()
mock_server.name = "test" # Set name as an attribute
mock_import.return_value = mock_server
# Install with a new env var
result = runner.invoke(
app,
["install", str(mock_server_file), "--env-var", "NEW=value"],
["install", str(server_file), "--env-var", "NEW=value"],
)
assert result.exit_code == 0
@ -169,7 +153,7 @@ def test_install_preserves_existing_env_vars(mock_config, mock_server_file):
assert server["env"] == {"FOO": "bar", "BAZ": "123", "NEW": "value"}
def test_install_updates_existing_env_vars(mock_config, mock_server_file):
def test_install_updates_existing_env_vars(mock_config, server_file):
"""Test that installing updates existing environment variables."""
# Set up initial config with env vars
config = {
@ -182,7 +166,7 @@ def test_install_updates_existing_env_vars(mock_config, mock_server_file):
"fastmcp",
"fastmcp",
"run",
str(mock_server_file),
str(server_file),
],
"env": {"FOO": "bar", "BAZ": "123"},
}
@ -192,19 +176,13 @@ def test_install_updates_existing_env_vars(mock_config, mock_server_file):
runner = CliRunner()
with (
patch("fastmcp.cli.claude.get_claude_config_path") as mock_config_path,
patch("fastmcp.cli.cli._import_server") as mock_import,
):
with patch("fastmcp.cli.claude.get_claude_config_path") as mock_config_path:
mock_config_path.return_value = mock_config.parent
mock_server = Mock()
mock_server.name = "test" # Set name as an attribute
mock_import.return_value = mock_server
# Update an existing env var
result = runner.invoke(
app,
["install", str(mock_server_file), "--env-var", "FOO=newvalue"],
["install", str(server_file), "--env-var", "FOO=newvalue"],
)
assert result.exit_code == 0
@ -213,3 +191,101 @@ def test_install_updates_existing_env_vars(mock_config, mock_server_file):
config = json.loads(mock_config.read_text())
server = next(iter(config["mcpServers"].values()))
assert server["env"] == {"FOO": "newvalue", "BAZ": "123"}
def test_server_dependencies(mock_config, server_file):
"""Test that server dependencies are correctly handled."""
# Create a server file with dependencies
server_file = server_file.parent / "server_with_deps.py"
server_file.write_text(
"""from fastmcp import FastMCP
mcp = FastMCP("test", dependencies=["pandas", "numpy"])
"""
)
runner = CliRunner()
with patch("fastmcp.cli.claude.get_claude_config_path") as mock_config_path:
mock_config_path.return_value = mock_config.parent
result = runner.invoke(app, ["install", str(server_file)])
assert result.exit_code == 0
# Read the config file and check dependencies were added as --with args
config = json.loads(mock_config.read_text())
server = next(iter(config["mcpServers"].values()))
assert "--with" in server["args"]
assert "pandas" in server["args"]
assert "numpy" in server["args"]
def test_server_dependencies_empty(mock_config, server_file):
"""Test that server with no dependencies works correctly."""
runner = CliRunner()
with patch("fastmcp.cli.claude.get_claude_config_path") as mock_config_path:
mock_config_path.return_value = mock_config.parent
result = runner.invoke(app, ["install", str(server_file)])
assert result.exit_code == 0
# Read the config file and check only fastmcp is in --with args
config = json.loads(mock_config.read_text())
server = next(iter(config["mcpServers"].values()))
assert server["args"].count("--with") == 1
assert "fastmcp" in server["args"]
def test_dev_with_dependencies(mock_config, server_file):
"""Test that dev command handles dependencies correctly."""
# Create a server file with dependencies
server_file = server_file.parent / "server_with_deps.py"
server_file.write_text(
"""from fastmcp import FastMCP
mcp = FastMCP("test", dependencies=["pandas", "numpy"])
"""
)
runner = CliRunner()
with patch("subprocess.run") as mock_run:
mock_run.return_value.returncode = 0 # Set successful return code
result = runner.invoke(app, ["dev", str(server_file)])
assert result.exit_code == 0
# Check that dependencies were passed to subprocess.run
mock_run.assert_called_once()
args = mock_run.call_args[0][0]
assert "npx" in args
assert "@modelcontextprotocol/inspector" in args
assert "uv" in args
assert "run" in args
assert "--with" in args
assert "pandas" in args
assert "numpy" in args
assert "fastmcp" in args
def test_run_with_dependencies(mock_config, server_file):
"""Test that run command does not handle dependencies."""
# Create a server file with dependencies
server_file = server_file.parent / "server_with_deps.py"
server_file.write_text(
"""from fastmcp import FastMCP
mcp = FastMCP("test", dependencies=["pandas", "numpy"])
if __name__ == "__main__":
mcp.run()
"""
)
runner = CliRunner()
with patch("subprocess.run") as mock_run:
result = runner.invoke(app, ["run", str(server_file)])
assert result.exit_code == 0
# Run command should not call subprocess.run
mock_run.assert_not_called()