ceos/fastmcp
1
0
Fork 0
mirror of https://github.com/PrefectHQ/fastmcp.git synced 2026-08-21 13:04:18 +02:00
Code Issues Projects Releases Packages Wiki Activity

fastmcp run works with remote servers

Browse source
This commit is contained in:
Jeremiah Lowin 2025-05-17 15:04:55 -04:00
commit 5aacd0b3ca
5 changed files with 236 additions and 146 deletions
Download patch file Download diff file Expand all files Collapse all files

17
docs/deployment/cli.mdx
View file

@ -27,7 +27,7 @@ fastmcp --help
### `run`
Run a FastMCP server directly.
Run a FastMCP server directly or proxy a remote server.
```bash
fastmcp run server.py
@ -48,12 +48,13 @@ This command runs the server directly in your current Python environment. You ar
#### Server Specification
The server can be specified in two ways:
The server can be specified in three ways:
1. `server.py` - imports the module and looks for a FastMCP object named `mcp`, `server`, or `app`. Errors if no such object is found.
2. `server.py:custom_name` - imports and uses the specified server object
3. `http://server-url/path` or `https://server-url/path` - connects to a remote server and creates a proxy
<Tip>
When using `fastmcp run`, it **ignores** the `if __name__ == "__main__"` block entirely. Instead, it finds your server object and calls its `run()` method directly with the transport options you specify. This means you can use `fastmcp run` to override the transport specified in your code.
When using `fastmcp run` with a local file, it **ignores** the `if __name__ == "__main__"` block entirely. Instead, it finds your server object and calls its `run()` method directly with the transport options you specify. This means you can use `fastmcp run` to override the transport specified in your code.
</Tip>
For example, if your code contains:
@ -79,11 +80,17 @@ You can run it with Streamable HTTP transport regardless of what's in the `__mai
fastmcp run server.py --transport streamable-http --port 8000
```
**Example**
**Examples**
```bash
# Run a server with Streamable HTTP transport on a custom port
# Run a local server with Streamable HTTP transport on a custom port
fastmcp run server.py --transport streamable-http --port 8000
# Connect to a remote server and proxy as a stdio server
fastmcp run https://example.com/mcp-server
# Connect to a remote server with specified log level
fastmcp run https://example.com/mcp-server --log-level DEBUG
```
### `dev`

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

@ -17,6 +17,7 @@ from typer import Context, Exit
import fastmcp
from fastmcp.cli import claude
from fastmcp.cli import run as run_module
from fastmcp.utilities.logging import get_logger
logger = get_logger("cli")
@ -58,7 +59,7 @@ def _parse_env_var(env_var: str) -> tuple[str, str]:
def _build_uv_command(
file_spec: str,
server_spec: str,
with_editable: Path | None = None,
with_packages: list[str] | None = None,
) -> list[str]:
@ -76,106 +77,10 @@ def _build_uv_command(
cmd.extend(["--with", pkg])
# Add mcp run command
cmd.extend(["fastmcp", "run", file_spec])
cmd.extend(["fastmcp", "run", server_spec])
return cmd
def _parse_file_path(file_spec: str) -> tuple[Path, str | None]:
"""Parse a file path that may include a server object specification.
Args:
file_spec: Path to file, optionally with :object suffix
Returns:
Tuple of (file_path, server_object)
"""
# First check if we have a Windows path (e.g., C:\...)
has_windows_drive = len(file_spec) > 1 and file_spec[1] == ":"
# Split on the last colon, but only if it's not part of the Windows drive letter
# and there's actually another colon in the string after the drive letter
if ":" in (file_spec[2:] if has_windows_drive else file_spec):
file_str, server_object = file_spec.rsplit(":", 1)
else:
file_str, server_object = file_spec, None
# Resolve the file path
file_path = Path(file_str).expanduser().resolve()
if not file_path.exists():
logger.error(f"File not found: {file_path}")
sys.exit(1)
if not file_path.is_file():
logger.error(f"Not a file: {file_path}")
sys.exit(1)
return file_path, server_object
def _import_server(file: Path, server_object: str | None = None):
"""Import a MCP server from a file.
Args:
file: Path to the file
server_object: Optional object name in format "module:object" or just "object"
Returns:
The server object
"""
# Add parent directory to Python path so imports can be resolved
file_dir = str(file.parent)
if file_dir not in sys.path:
sys.path.insert(0, file_dir)
# Import the module
spec = importlib.util.spec_from_file_location("server_module", file)
if not spec or not spec.loader:
logger.error("Could not load module", extra={"file": str(file)})
sys.exit(1)
module = importlib.util.module_from_spec(spec)
spec.loader.exec_module(module)
# If no object specified, try common server names
if not server_object:
# Look for the most common server object names
for name in ["mcp", "server", "app"]:
if hasattr(module, name):
return getattr(module, name)
logger.error(
f"No server object found in {file}. Please either:\n"
"1. Use a standard variable name (mcp, server, or app)\n"
"2. Specify the object name with file:object syntax",
extra={"file": str(file)},
)
sys.exit(1)
# Handle module:object syntax
if ":" in server_object:
module_name, object_name = server_object.split(":", 1)
try:
server_module = importlib.import_module(module_name)
server = getattr(server_module, object_name, None)
except ImportError:
logger.error(
f"Could not import module '{module_name}'",
extra={"file": str(file)},
)
sys.exit(1)
else:
# Just object name
server = getattr(module, server_object, None)
if server is None:
logger.error(
f"Server object '{server_object}' not found",
extra={"file": str(file)},
)
sys.exit(1)
return server
@app.command()
def version(ctx: Context):
if ctx.resilient_parsing:
@ -201,7 +106,7 @@ def version(ctx: Context):
@app.command()
def dev(
file_spec: str = typer.Argument(
server_spec: str = typer.Argument(
...,
help="Python file to run, optionally with :object suffix",
),
@ -246,7 +151,7 @@ def dev(
] = None,
) -> None:
"""Run a MCP server with the MCP Inspector."""
file, server_object = _parse_file_path(file_spec)
file, server_object = run_module.parse_file_path(server_spec)
logger.debug(
"Starting dev server",
@ -262,7 +167,7 @@ def dev(
try:
# Import server to get dependencies
server = _import_server(file, server_object)
server = run_module.import_server(file, server_object)
if hasattr(server, "dependencies") and server.dependencies is not None:
with_packages = list(set(with_packages + server.dependencies))
@ -285,7 +190,7 @@ def dev(
if inspector_version:
inspector_cmd += f"@{inspector_version}"
uv_cmd = _build_uv_command(file_spec, with_editable, with_packages)
uv_cmd = _build_uv_command(server_spec, with_editable, with_packages)
# Run the MCP Inspector command with shell=True on Windows
shell = sys.platform == "win32"
@ -318,9 +223,9 @@ def dev(
@app.command()
def run(
file_spec: str = typer.Argument(
server_spec: str = typer.Argument(
...,
help="Python file to run, optionally with :object suffix",
help="Python file, object specification (file:obj), or URL",
),
transport: Annotated[
str | None,
@ -354,22 +259,20 @@ def run(
),
] = None,
) -> None:
"""Run a MCP server.
"""Run a MCP server or connect to a remote one.
The server can be specified in two ways:
1. Module approach: server.py - runs the module directly, expecting a server.run() call.\n
2. Import approach: server.py:app - imports and runs the specified server object.\n\n
The server can be specified in three ways:
1. Module approach: server.py - runs the module directly, looking for an object named mcp/server/app.\n
2. Import approach: server.py:app - imports and runs the specified server object.\n
3. URL approach: http://server-url - connects to a remote server and creates a proxy.\n\n
Note: This command runs the server directly. You are responsible for ensuring
all dependencies are available.
"""
file, server_object = _parse_file_path(file_spec)
logger.debug(
"Running server",
"Running server or client",
extra={
"file": str(file),
"server_object": server_object,
"server_spec": server_spec,
"transport": transport,
"host": host,
"port": port,
@ -378,29 +281,18 @@ def run(
)
try:
# Import and get server object
server = _import_server(file, server_object)
logger.info(f'Found server "{server.name}" in {file}')
# Run the server
kwargs = {}
if transport:
kwargs["transport"] = transport
if host:
kwargs["host"] = host
if port:
kwargs["port"] = port
if log_level:
kwargs["log_level"] = log_level
server.run(**kwargs)
run_module.run_command(
server_spec=server_spec,
transport=transport,
host=host,
port=port,
log_level=log_level,
)
except Exception as e:
logger.error(
f"Failed to run server: {e}",
f"Failed to run: {e}",
extra={
"file": str(file),
"server_spec": server_spec,
"error": str(e),
},
)
@ -409,7 +301,7 @@ def run(
@app.command()
def install(
file_spec: str = typer.Argument(
server_spec: str = typer.Argument(
...,
help="Python file to run, optionally with :object suffix",
),
@ -466,7 +358,7 @@ def install(
Environment variables are preserved once added and only updated if new values
are explicitly provided.
"""
file, server_object = _parse_file_path(file_spec)
file, server_object = run_module.parse_file_path(server_spec)
logger.debug(
"Installing server",
@ -489,7 +381,7 @@ def install(
server = None
if not name:
try:
server = _import_server(file, server_object)
server = run_module.import_server(file, server_object)
name = server.name
except (ImportError, ModuleNotFoundError) as e:
logger.debug(
@ -526,7 +418,7 @@ def install(
env_dict[key] = value
if claude.update_claude_config(
file_spec,
server_spec,
name,
with_editable=with_editable,
with_packages=with_packages,

179
src/fastmcp/cli/run.py Normal file
View file

@ -0,0 +1,179 @@
"""FastMCP run command implementation."""
import importlib.util
import re
import sys
from pathlib import Path
from typing import Any, Literal
from fastmcp.utilities.logging import get_logger
logger = get_logger("cli.run")
TransportType = Literal["stdio", "streamable-http", "sse"]
def is_url(path: str) -> bool:
"""Check if a string is a URL."""
url_pattern = re.compile(r"^https?://")
return bool(url_pattern.match(path))
def parse_file_path(server_spec: str) -> tuple[Path, str | None]:
"""Parse a file path that may include a server object specification.
Args:
server_spec: Path to file, optionally with :object suffix
Returns:
Tuple of (file_path, server_object)
"""
# First check if we have a Windows path (e.g., C:\...)
has_windows_drive = len(server_spec) > 1 and server_spec[1] == ":"
# Split on the last colon, but only if it's not part of the Windows drive letter
# and there's actually another colon in the string after the drive letter
if ":" in (server_spec[2:] if has_windows_drive else server_spec):
file_str, server_object = server_spec.rsplit(":", 1)
else:
file_str, server_object = server_spec, None
# Resolve the file path
file_path = Path(file_str).expanduser().resolve()
if not file_path.exists():
logger.error(f"File not found: {file_path}")
sys.exit(1)
if not file_path.is_file():
logger.error(f"Not a file: {file_path}")
sys.exit(1)
return file_path, server_object
def import_server(file: Path, server_object: str | None = None) -> Any:
"""Import a MCP server from a file.
Args:
file: Path to the file
server_object: Optional object name in format "module:object" or just "object"
Returns:
The server object
"""
# Add parent directory to Python path so imports can be resolved
file_dir = str(file.parent)
if file_dir not in sys.path:
sys.path.insert(0, file_dir)
# Import the module
spec = importlib.util.spec_from_file_location("server_module", file)
if not spec or not spec.loader:
logger.error("Could not load module", extra={"file": str(file)})
sys.exit(1)
module = importlib.util.module_from_spec(spec)
spec.loader.exec_module(module)
# If no object specified, try common server names
if not server_object:
# Look for the most common server object names
for name in ["mcp", "server", "app"]:
if hasattr(module, name):
return getattr(module, name)
logger.error(
f"No server object found in {file}. Please either:\n"
"1. Use a standard variable name (mcp, server, or app)\n"
"2. Specify the object name with file:object syntax",
extra={"file": str(file)},
)
sys.exit(1)
# Handle module:object syntax
if ":" in server_object:
module_name, object_name = server_object.split(":", 1)
try:
server_module = importlib.import_module(module_name)
server = getattr(server_module, object_name, None)
except ImportError:
logger.error(
f"Could not import module '{module_name}'",
extra={"file": str(file)},
)
sys.exit(1)
else:
# Just object name
server = getattr(module, server_object, None)
if server is None:
logger.error(
f"Server object '{server_object}' not found",
extra={"file": str(file)},
)
sys.exit(1)
return server
def create_client_server(url: str) -> Any:
"""Create a FastMCP server from a client URL.
Args:
url: The URL to connect to
Returns:
A FastMCP server instance
"""
try:
import fastmcp
client = fastmcp.Client(url)
server = fastmcp.FastMCP.from_client(client)
return server
except Exception as e:
logger.error(f"Failed to create client for URL {url}: {e}")
sys.exit(1)
def run_command(
server_spec: str,
transport: str | None = None,
host: str | None = None,
port: int | None = None,
log_level: str | None = None,
) -> None:
"""Run a MCP server or connect to a remote one.
Args:
server_spec: Python file, object specification (file:obj), or URL
transport: Transport protocol to use
host: Host to bind to when using http transport
port: Port to bind to when using http transport
log_level: Log level
"""
if is_url(server_spec):
# Handle URL case
server = create_client_server(server_spec)
logger.debug(f"Created client proxy server for {server_spec}")
else:
# Handle file case
file, server_object = parse_file_path(server_spec)
server = import_server(file, server_object)
logger.debug(f'Found server "{server.name}" in {file}')
# Run the server
kwargs = {}
if transport:
kwargs["transport"] = transport
if host:
kwargs["host"] = host
if port:
kwargs["port"] = port
if log_level:
kwargs["log_level"] = log_level
try:
server.run(**kwargs)
except Exception as e:
logger.error(f"Failed to run server: {e}")
sys.exit(1)

3
src/fastmcp/server/http.py
View file

@ -254,6 +254,7 @@ def create_sse_app(
)
# Store the FastMCP server instance on the Starlette app state
app.state.fastmcp_server = server
app.state.path = sse_path
return app
@ -357,4 +358,6 @@ def create_streamable_http_app(
# Store the FastMCP server instance on the Starlette app state
app.state.fastmcp_server = server
app.state.path = streamable_http_path
return app

17
src/fastmcp/server/server.py
View file

@ -213,7 +213,7 @@ class FastMCP(Generic[LifespanResultT]):
Args:
transport: Transport protocol to use ("stdio", "sse", or "streamable-http")
"""
logger.info(f'Starting server "{self.name}"...')
logger.debug(f'Starting server "{self.name}"...')
anyio.run(partial(self.run_async, transport, **transport_kwargs))
@ -730,6 +730,7 @@ class FastMCP(Generic[LifespanResultT]):
async def run_stdio_async(self) -> None:
"""Run the server using stdio transport."""
async with stdio_server() as (read_stream, write_stream):
logger.info(f"Starting MCP server {self.name!r} with transport 'stdio'")
await self._mcp_server.run(
read_stream,
write_stream,
@ -763,16 +764,24 @@ class FastMCP(Generic[LifespanResultT]):
# lifespan is required for streamable http
uvicorn_config["lifespan"] = "on"
host = host or self.settings.host
port = port or self.settings.port
log_level = log_level or self.settings.log_level.lower()
app = self.http_app(path=path, transport=transport, middleware=middleware)
config = uvicorn.Config(
app,
host=host or self.settings.host,
port=port or self.settings.port,
log_level=log_level or self.settings.log_level.lower(),
host=host,
port=port,
log_level=log_level,
**uvicorn_config,
)
server = uvicorn.Server(config)
path = app.state.path.lstrip("/") # type: ignore
logger.info(
f"Starting MCP server {self.name!r} with transport {transport!r} on http://{host}:{port}/{path}"
)
await server.serve()
async def run_sse_async(