Skip to content

πŸš€ 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.mdx
index 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.
```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`
diff --git a/src/fastmcp/cli/cli.py b/src/fastmcp/cli/cli.py
index feda85a0e..819144d22 100644
--- a/src/fastmcp/cli/cli.py
+++ b/src/fastmcp/cli/cli.py
@@ -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,
diff --git a/src/fastmcp/cli/run.py b/src/fastmcp/cli/run.py
new file mode 100644
index 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.py
index 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 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
diff --git a/src/fastmcp/server/server.py b/src/fastmcp/server/server.py
index 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 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(