Running Servers

import { VersionBadge } from '/snippets/version-badge.mdx'

Starting a Server

fastmcp run starts a server. Point it at a Python file, a factory function, a remote URL, or a config file:

fastmcp run server.py
fastmcp run server.py:create_server
fastmcp run https://example.com/mcp
fastmcp run fastmcp.json

By default, the server runs over stdio — the transport that MCP clients like Claude Desktop expect. To serve over HTTP instead, specify the transport:

fastmcp run server.py --transport http
fastmcp run server.py --transport http --host 0.0.0.0 --port 9000

Entrypoints

FastMCP supports several ways to locate and start your server:

Inferred instance — FastMCP imports the file and looks for a variable named mcp, server, or app:

fastmcp run server.py

Explicit instance — point at a specific variable:

fastmcp run server.py:my_server

Factory function — FastMCP calls the function and uses the returned server. Useful when your server needs async setup or configuration that runs before startup:

fastmcp run server.py:create_server

Remote URL — starts a local proxy that bridges to a remote server. Handy for local development against a deployed server, or for bridging a remote HTTP server to stdio:

fastmcp run https://example.com/mcp

FastMCP config — uses a fastmcp.json file that declaratively specifies the server, its dependencies, and deployment settings. When you run fastmcp run with no arguments, it auto-detects fastmcp.json in the current directory:

fastmcp run
fastmcp run my-config.fastmcp.json

See Server Configuration for the full fastmcp.json format.

MCP config — runs servers defined in a standard MCP configuration file (any .json with an mcpServers key):

fastmcp run mcp.json

Options

Dependency Management

By default, fastmcp run uses your current Python environment directly. When you pass --python, --with, --project, or --with-requirements, it switches to running via uv run in a subprocess, which handles dependency isolation automatically.

The --skip-env flag is useful when you're already inside an activated venv, a Docker container with pre-installed dependencies, or a uv-managed project — it prevents uv from trying to set up another environment layer.

Previewing Apps

fastmcp dev apps launches a browser-based preview UI for servers with Prefab App tools. It starts your MCP server on one port and a local dev UI on another — giving you a live, interactive picker where you can call app tools and see their rendered output without needing a full MCP host client.

fastmcp dev apps server.py
fastmcp dev apps server.py:mcp --mcp-port 9000 --dev-port 9090

The picker auto-generates a form from each tool's input schema. Submit the form and the result opens in a new tab as a rendered Prefab UI.

Auto-reload is on by default — save a file and the MCP server restarts automatically.

Development with the Inspector

fastmcp dev inspector launches your server inside the MCP Inspector, a browser-based tool for interactively testing MCP servers. Auto-reload is on by default, so your server restarts when you save changes.

fastmcp dev inspector server.py
fastmcp dev inspector server.py -e . --with pandas

Pre-Building Environments

fastmcp project prepare creates a persistent uv project from a fastmcp.json file, pre-installing all dependencies. This separates environment setup from server execution — install once, run many times.

# Step 1: Build the environment (slow, does dependency resolution)
fastmcp project prepare fastmcp.json --output-dir ./env

# Step 2: Run using the prepared environment (fast, no install step)
fastmcp run fastmcp.json --project ./env

The prepared directory contains a pyproject.toml, a .venv with all packages installed, and a uv.lock for reproducibility. This is particularly useful in deployment scenarios where you want deterministic, pre-built environments.