Some links on this page are affiliate links: if you buy through them we may earn a commission, at no extra cost to you.
FastMCP reduces an MCP server to ordinary Python functions, type annotations, and a few commands. Install the standalone fastmcp package, create a FastMCP instance, decorate a function with @mcp.tool, and run the file. FastMCP derives the tool schema, validation, and documentation from your function declaration.
This guide builds a working server first, then covers stdio and HTTP transports, the MCP Inspector, project reproducibility, common failures, and the difference between standalone FastMCP and the similarly named class bundled in the MCP Python SDK.
What you will build
The example exposes an add tool. An MCP client can discover it, see that it accepts two integers, and call it without you hand-writing a JSON schema. The same pattern scales to tools that query databases, call APIs, manipulate files, or perform other controlled operations.
PC Slower Than It Used to Be?
A free scan shows the junk files, broken settings and background clutter dragging Windows down - then fixes them in one click.Free scan · Windows 10 & 11Crashes, No Sound, or Screen Glitches?
Random freezes, missing sound and display glitches usually trace back to one bad driver. Find and replace yours safely.Free scan · under a minute- Python project managed with standalone FastMCP.
- One typed tool with a useful docstring.
- Local stdio execution for desktop clients and command-line integrations.
- Optional Streamable HTTP execution for a separately hosted service.
- Browser-based inspection with MCP Inspector.
FastMCP also supports MCP resources (data a client can read) and prompts (reusable prompt templates). A small server does not need all three; start with tools and add the other primitives when your use case calls for them.
#1 Best Overall
Install FastMCP in a Python project
Recommended project setup with uv
- Install uv if it is not already available on your system.
- Create and enter a project directory:
mkdir fastmcp-demo cd fastmcp-demo uv init - Add the standalone package:
uv add fastmcp
The package/import pair is intentional: this workflow installs fastmcp and imports FastMCP from fastmcp. Keep that pairing consistent throughout the project.
Confirm the environment
Run commands through the project environment so the interpreter and CLI use the locked dependency set:
uv run python --version
uv run fastmcp --helpIf your organization uses another environment manager, install the fastmcp package there and invoke the equivalent interpreter. The important requirement is that the Python process running the server and the FastMCP CLI see the same installation.
Create the minimum server
Create server.py with this complete example:
from fastmcp import FastMCP
mcp = FastMCP("Demo")
@mcp.tool
def add(a: int, b: int) -> int:
"""Add two numbers."""
return a + b
if __name__ == "__main__":
mcp.run()What each line does
FastMCP("Demo")creates the server and gives it a human-readable name.@mcp.toolregisters the decorated function as an MCP tool.a: int,b: int, and-> intdescribe inputs and output. FastMCP uses the declaration to generate schema and validation.- The docstring becomes part of the tool description shown to clients.
- The
__main__block lets you launch the file directly with Python. It is useful for direct execution, but thefastmcp runcommand does not execute this block.
Use descriptive names, precise annotations, and docstrings that explain side effects, units, and expected values. Those details become the interface an AI client relies on.
Run the server over stdio
For a local MCP client, use the CLI:
uv run fastmcp run server.pyStdio is the documented default transport. The command starts the server and communicates through its standard input and output, which is why it is commonly used by local desktop clients and CLI integrations. Do not print diagnostic messages to standard output while the server is running; unsolicited output can corrupt the protocol stream. Send diagnostics to standard error or use a logger configured for stderr.
You can also run the file directly:
uv run python server.pyThat path enters the if __name__ == "__main__" block and calls mcp.run(). The CLI path is generally more convenient when you want FastMCP to discover an instance or choose a transport.
Explicit instance and factory forms
FastMCP can infer common variable names such as mcp, server, or app. If your instance has another name, identify it explicitly:
uv run fastmcp run server.py:my_serverFor a factory function, use a colon-qualified target:
uv run fastmcp run server.py:create_serverPut required initialization in the factory when using this form. Because fastmcp run ignores the Python __main__ block, setup placed only there will not run.
Run an HTTP server
Choose HTTP when a client must connect to a separately running service rather than launch a local process. The CLI documentation selects HTTP explicitly:
uv run fastmcp run server.py --transport httpThe documented HTTP defaults are host 127.0.0.1, port 8000, and path /mcp. To listen on all interfaces and use port 9000:
Free tools Windows power users keep installed
One-click scans. No signup required.
uv run fastmcp run server.py --transport http --host 0.0.0.0 --port 9000Binding to 0.0.0.0 makes the process reachable on the machine’s network interfaces. Restrict access with your deployment network and authentication layer before exposing it beyond a trusted environment. The CLI documentation also lists SSE as a selectable transport; transport support and defaults can change, so check the current guide when integrating a client or deploying a long-lived service.
Stdio or HTTP?
| Situation | Better starting point | Reason |
|---|---|---|
| One developer’s local MCP client launches the server | stdio | No listening socket or separate service process is required. |
| A remote client needs a network endpoint | HTTP | The client can connect to the running URL. |
| Testing a new tool quickly | stdio | The default command has the fewest moving parts. |
| Container or hosted deployment | HTTP | Process and client can be deployed independently. |
Client compatibility, network policy, and your hosting environment should decide the final transport. Do not assume a client supports every transport listed by the CLI.
Inspect the server with MCP Inspector
Use the development Inspector command:
uv run fastmcp dev inspector server.pyThis launches the browser-based MCP Inspector workflow. The CLI documentation says auto-reload is enabled by default, so changes to the server can be picked up during development. The Inspector connects over stdio for this command; use it to discover the add tool, inspect its generated schema, and send a test call.
For an HTTP server, start it separately:
uv run fastmcp run server.py --transport http --port 9000Then open the Inspector and direct it to the HTTP URL exposed by your server, including its MCP path when required by the client configuration. Keeping the HTTP process separate is important: the Inspector command itself is documented as a stdio workflow.
Make a tool useful and safe
Design the Python signature as the API
Prefer narrow parameters and explicit return types. For example, use limit: int with a documented maximum instead of accepting an unstructured dictionary. Explain whether a function changes data, accesses the network, or can take a long time. Validation generated from annotations catches malformed calls before your implementation runs, but business rules such as authorization and rate limits still belong in your code or deployment layer.
Add resources and prompts only when needed
Tools perform operations. Resources expose read-oriented data, and prompts provide reusable prompt patterns. They are separate MCP concepts; adding them is useful when clients need those interaction styles, not a requirement for every FastMCP server.
Reproducible projects for deployment
A single server.py is enough to learn the protocol. As dependencies and configuration grow, FastMCP documents fastmcp.json and a fastmcp project prepare flow. That preparation creates a uv project with dependencies and a lock file, which is useful for deterministic prebuilt deployment environments. Treat it as an optional next step after the basic server works, and keep the generated lock file with the project so deployment uses the versions you approved.
Standalone FastMCP versus the MCP SDK class
Two official code paths use the name FastMCP:
| Context | Install/distribution | Import shown in its documentation |
|---|---|---|
| Standalone Prefect project | fastmcp package |
from fastmcp import FastMCP |
| MCP Python SDK documentation consulted | SDK-bundled implementation | from mcp.server.fastmcp import FastMCP |
These import paths are not interchangeable instructions. The SDK page referenced here is explicitly v1 maintenance documentation and states that v2 is the current stable line. Before copying SDK examples into a new project, check the current SDK installation and quickstart pages for the version you intend to use. This article’s commands target the standalone package.
Quick wins for a faster PC:
Repair Windows errors before they cause bigger problemsFix Now →Fix the driver behind crashes, sound loss and screen glitchesFind Drivers →Troubleshooting
“No module named fastmcp”
The command is using a different interpreter from the project environment. Run it with uv run, verify uv add fastmcp completed, and check that your editor’s interpreter points at the project environment.
The CLI cannot find a server
Use the file path relative to your current directory and ensure the file defines an inferred variable named mcp, server, or app. Otherwise qualify the instance, for example server.py:my_server, or provide a factory target.
Changes in the main block do not happen
fastmcp run ignores if __name__ == "__main__". Move mandatory initialization into module-level setup or a factory function and invoke that target explicitly.
The Inspector shows no tools
Confirm the function has the @mcp.tool decorator, is imported before the server starts, and has valid Python syntax. Restart the Inspector after changing the server if auto-reload did not pick up an import-time error, then read the terminal’s stderr output.
HTTP clients cannot connect
Check the host, port, and MCP path, and confirm the process is still running. A server bound to 127.0.0.1 is reachable only from the local machine; a container or remote client may require an appropriate bind address and network rule. Verify the client’s transport support before changing server code.
Protocol errors appear immediately
For stdio, remove ordinary print() calls from code that runs while the server is connected. Write diagnostics to stderr so stdout remains reserved for MCP messages.
Or skip the browser setup
If your MCP project needs screenshots as a tool, ScreenshotNeo provides a website screenshot API and MCP server. A single GET request returns PNG, JPEG, WebP, or PDF output, so you can register the call as a FastMCP tool instead of maintaining browser automation.
cURL (see the ScreenshotNeo documentation):
curl -G "https://api.screenshotneo.com/v1/shot" -d access_key=YOUR_API_KEY --data-urlencode url=https://stripe.com -o shot.webpPython:
import requests
r = requests.get("https://api.screenshotneo.com/v1/shot", params={"access_key": "YOUR_API_KEY", "url": "https://stripe.com"}, timeout=90)
open("shot.webp", "wb").write(r.content)Node.js:
const q = new URLSearchParams({ access_key: 'YOUR_API_KEY', url: 'https://stripe.com' });
const res = await fetch(`https://api.screenshotneo.com/v1/shot?${q}`);Before capture, ScreenshotNeo accepts cookie or consent banners and removes more than 60 known consent platforms, newsletter popups, and chat widgets; each cleanup step can be disabled. Bot checks or CAPTCHAs, blank pages, timeouts, failed loads, and cache hits are not billed, and response headers report the page verdict and whether it was billed. Its MCP server includes take_screenshot, get_page_info, and capture_pdf for Claude, Cursor, and other MCP clients. The free plan includes 1,000 screenshots per month with no card; paid plans start at $5 for 3,000 shots. Sign up for the free ScreenshotNeo plan.
The Tool Desk
Outbyte Driver Updater FREEFix the driver behind crashes, sound loss and screen glitchesFind Drivers →Outbyte PC Repair FREEClear out junk files and repair common Windows errorsFree Scan →Practical checklist
- Install the standalone package with
uv add fastmcp. - Import from
fastmcp, not the SDK path, for this tutorial. - Create a named
FastMCPinstance. - Decorate typed functions with
@mcp.tool. - Use docstrings to describe behavior and side effects.
- Start locally with stdio before introducing HTTP networking.
- Inspect tools with
fastmcp dev inspector server.py. - Use an explicit instance or factory when inference is insufficient.
- Keep stdout clean for stdio protocol traffic.
- Recheck current FastMCP and SDK documentation before pinning versions for production.
Frequently Asked Questions
Can one FastMCP server expose more than one tool?
Yes. Define additional functions and decorate each with the same server instance’s @mcp.tool decorator.
Does FastMCP require HTTP?
No. The documented default is stdio, which is appropriate for many local MCP clients. Select HTTP explicitly when a network endpoint is needed.
Why are annotations and docstrings important?
They describe the generated interface that clients discover: annotations contribute types and validation, while the docstring explains the operation.
Should I import from mcp.server.fastmcp or fastmcp?
Use the import that matches the distribution you installed. This guide uses the standalone fastmcp package; the SDK-bundled class is a separate context with its own version documentation.
Recommended Free Tools
Quick Recap
Product prices and availability are accurate as of the date/time indicated and are subject to change. Any price and availability information displayed on Amazon at the time of purchase will apply.
