π The fast, Pythonic way to build MCP servers and clients.
fastmcp run works with remote servers
Jeremiah Lowin5aacd0b3ca9e
diff --git a/docs/deployment/cli.mdx b/docs/deployment/cli.mdxindex 1397d8aeb..a010722d2 100644--- a/docs/deployment/cli.mdx+++ b/docs/deployment/cli.mdx@@ -27,7 +27,7 @@ fastmcp --help### `run`-Run a FastMCP server directly.+Run a FastMCP server directly or proxy a remote server.```bashfastmcp 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 `__maifastmcp 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 portfastmcp 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`diff --git a/src/fastmcp/cli/cli.py b/src/fastmcp/cli/cli.pyindex feda85a0e..819144d22 100644--- a/src/fastmcp/cli/cli.py+++ b/src/fastmcp/cli/cli.py@@ -17,6 +17,7 @@ from typer import Context, Exitimport fastmcpfrom fastmcp.cli import claude+from fastmcp.cli import run as run_modulefrom fastmcp.utilities.logging import get_loggerlogger = 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 Windowsshell = 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\nNote: This command runs the server directly. You are responsible for ensuringall 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 valuesare 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 = Noneif not name:try:- server = _import_server(file, server_object)+ server = run_module.import_server(file, server_object)name = server.nameexcept (ImportError, ModuleNotFoundError) as e:logger.debug(@@ -526,7 +418,7 @@ def install(env_dict[key] = valueif claude.update_claude_config(- file_spec,+ server_spec,name,with_editable=with_editable,with_packages=with_packages,diff --git a/src/fastmcp/cli/run.py b/src/fastmcp/cli/run.pynew file mode 100644index 000000000..fc3bf1780--- /dev/null+++ b/src/fastmcp/cli/run.py@@ -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)diff --git a/src/fastmcp/server/http.py b/src/fastmcp/server/http.pyindex d718d610a..8655b2d64 100644--- a/src/fastmcp/server/http.py+++ b/src/fastmcp/server/http.py@@ -254,6 +254,7 @@ def create_sse_app()# Store the FastMCP server instance on the Starlette app stateapp.state.fastmcp_server = server+ app.state.path = sse_pathreturn app@@ -357,4 +358,6 @@ def create_streamable_http_app(# Store the FastMCP server instance on the Starlette app stateapp.state.fastmcp_server = server+ app.state.path = streamable_http_path+return appdiff --git a/src/fastmcp/server/server.py b/src/fastmcp/server/server.pyindex c6aaeedba..869368419 100644--- a/src/fastmcp/server/server.py+++ b/src/fastmcp/server/server.py@@ -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 httpuvicorn_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(