Skip to main content

​
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
fastmcp run completely ignores the if __name__ == "__main__" block. Any setup code in that block won’t execute. If you need initialization logic to run, use a factory function.

​
Options

OptionFlagDescription
Transport--transport, -tstdio (default), http, or sse
Host--hostBind address for HTTP (default: 127.0.0.1)
Port--port, -pBind port for HTTP (default: 8000)
Path--pathURL path for HTTP (default: /mcp/)
Log Level--log-level, -lDEBUG, INFO, WARNING, ERROR, CRITICAL
No Banner--no-bannerSuppress the startup banner
Auto-Reload--reload / --no-reloadWatch for file changes and restart automatically
Reload Dirs--reload-dirDirectories to watch (repeatable)
Skip Env--skip-envDon’t set up a uv environment (use when already in one)
Python--pythonPython version to use (e.g., 3.11)
Extra Packages--withAdditional packages to install (repeatable)
Project--projectRun within a specific uv project directory
Requirements--with-requirementsInstall from a requirements file

​
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.
fastmcp dev apps requires fastmcp[apps] — install with pip install "fastmcp[apps]".
OptionFlagDescription
MCP Port--mcp-portPort for the MCP server (default: 8000)
Dev Port--dev-portPort for the dev UI (default: 8080)
Auto-Reload--reload / --no-reloadWatch for file changes (default: on)

​
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
The Inspector always runs your server via uv run in a subprocess — it never uses your local environment directly. Specify dependencies with --with, --with-editable, --with-requirements, or through a fastmcp.json file.
The Inspector connects over stdio only. When it launches, you may need to select “STDIO” from the transport dropdown and click connect. To test a server over HTTP, start it separately with fastmcp run server.py --transport http and point the Inspector at the URL.
OptionFlagDescription
Editable Package--with-editable, -eInstall a directory in editable mode
Extra Packages--withAdditional packages (repeatable)
Inspector Version--inspector-versionMCP Inspector version to use
UI Port--ui-portPort for the Inspector UI
Server Port--server-portPort for the Inspector proxy
Auto-Reload--reload / --no-reloadFile watching (default: on)
Reload Dirs--reload-dirDirectories to watch (repeatable)
Python--pythonPython version
Project--projectRun within a uv project directory
Requirements--with-requirementsInstall from a requirements file

​
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.