URL: https://gofastmcp.com/cli/running
Title: Running Servers - FastMCP

Documentation Index
Fetch the complete documentation index at:
/llms.txt
Use this file to discover all available pages before exploring further.
Skip to main content
Meet
Prefect Horizon
, the enterprise MCP gateway built by the team behind FastMCP
FastMCP
home page
v3
Prefect Horizon
PrefectHQ/fastmcp
25,596
PrefectHQ/fastmcp
25,596
Search...
Navigation
CLI
Running Servers
Search the docs...
Ctrl
K
Documentation
Get Started
Welcome!
Installation
Quickstart
Servers
Overview
Core Components
Working with Tools
MCP Providers
Interactivity
Extensibility
Auth
Deployment
Apps
Overview
Quickstart
NEW
FastMCPApp
NEW
Interactive Tools
NEW
Generative UI
NEW
Custom HTML
Reference
Clients
Overview
Client-Only Package
Transports
fastmcp-remote
Operations
UPDATED
Authentication
UPDATED
Integrations
Auth
Web Frameworks
AI Assistants
AI SDKs
MCP.json
More
Settings
CLI
Overview
Running
Install MCPs
Inspecting
Client
Generate CLI
Auth
Upgrading
Development
What's New
FAQ
On this page
Starting a Server
Entrypoints
Options
Dependency Management
Previewing Apps
Development with the Inspector
Pre-Building Environments
CLI
Running Servers
Copy page
Start, develop, and configure servers from the command line
Copy page
​
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
Option
Flag
Description
Transport
--transport
,
-t
stdio
(default),
http
, or
sse
Host
--host
Bind address for HTTP (default:
127.0.0.1
)
Port
--port
,
-p
Bind port for HTTP (default:
8000
)
Path
--path
URL path for HTTP (default:
/mcp/
)
Log Level
--log-level
,
-l
DEBUG
,
INFO
,
WARNING
,
ERROR
,
CRITICAL
No Banner
--no-banner
Suppress the startup banner
Auto-Reload
--reload
/
--no-reload
Watch for file changes and restart automatically
Reload Dirs
--reload-dir
Directories to watch (repeatable)
Skip Env
--skip-env
Don’t set up a uv environment (use when already in one)
Python
--python
Python version to use (e.g.,
3.11
)
Extra Packages
--with
Additional packages to install (repeatable)
Project
--project
Run within a specific uv project directory
Requirements
--with-requirements
Install 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
New in version
3.2.0
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]"
.
Option
Flag
Description
MCP Port
--mcp-port
Port for the MCP server (default:
8000
)
Dev Port
--dev-port
Port for the dev UI (default:
8080
)
Auto-Reload
--reload
/
--no-reload
Watch 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.
Option
Flag
Description
Editable Package
--with-editable
,
-e
Install a directory in editable mode
Extra Packages
--with
Additional packages (repeatable)
Inspector Version
--inspector-version
MCP Inspector version to use
UI Port
--ui-port
Port for the Inspector UI
Server Port
--server-port
Port for the Inspector proxy
Auto-Reload
--reload
/
--no-reload
File watching (default: on)
Reload Dirs
--reload-dir
Directories to watch (repeatable)
Python
--python
Python version
Project
--project
Run within a uv project directory
Requirements
--with-requirements
Install 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.
CLI
Previous
Install MCP Servers
Next
Ctrl
+I
discord
github
website
x
Powered by
This documentation is built and hosted on Mintlify, a developer documentation platform
Assistant
Responses are generated using AI and may contain mistakes.
\n\n
\n
\n \n
\n
