π The fast, Pythonic way to build MCP servers and clients.
Add -m/--module flag to fastmcp run and dev inspector
dgenio7a582ff5a06a
diff --git a/src/fastmcp/cli/cli.py b/src/fastmcp/cli/cli.pyindex 07b2ddb5b..1605f567b 100644--- a/src/fastmcp/cli/cli.py+++ b/src/fastmcp/cli/cli.py@@ -212,6 +212,13 @@ async def inspector(help="Directories to watch for changes (default: current directory)",),] = None,+ module: Annotated[+ bool,+ cyclopts.Parameter(+ name=["--module", "-m"],+ help="Run a Python module (python -m <module>) instead of importing a server object",+ ),+ ] = False,) -> None:"""Run an MCP server with the MCP Inspector for development.@@ -278,6 +285,10 @@ async def inspector(# Build the fastmcp run commandfastmcp_cmd = ["fastmcp", "run", server_spec, "--no-banner"]+ # Forward module mode flag+ if module:+ fastmcp_cmd.append("--module")+# Add reload flags if enabled - the server will handle reloadingif reload:fastmcp_cmd.append("--reload")@@ -424,6 +435,13 @@ async def run(help="Run in stateless mode (no session, used internally for reload)",),] = False,+ module: Annotated[+ bool,+ cyclopts.Parameter(+ name=["--module", "-m"],+ help="Run a Python module (python -m <module>) instead of importing a server object",+ ),+ ] = False,) -> None:"""Run an MCP server or connect to a remote one.@@ -434,6 +452,7 @@ async def run(4. MCPConfig file: "mcp.json" - runs as a proxy server for the MCP Servers in the MCPConfig file5. FastMCP config: "fastmcp.json" - runs server using FastMCP configuration6. No argument: looks for fastmcp.json in current directory+ 7. Module mode: "my_module -m" - runs the module directly via python -mServer arguments can be passed after -- :fastmcp run server.py -- --config config.json --debug@@ -442,6 +461,54 @@ async def run(server_spec: Python file, object specification (file:obj), config file, URL, or None to auto-detect"""+ # --- Module mode: delegate to python -m and exit early ---+ if module:+ if server_spec is None:+ logger.error("A module name is required when using --module / -m")+ sys.exit(1)++ # Warn about options that are ignored in module mode+ ignored_options: list[str] = []+ if transport:+ ignored_options.append("--transport")+ if host:+ ignored_options.append("--host")+ if port:+ ignored_options.append("--port")+ if path:+ ignored_options.append("--path")+ if reload:+ ignored_options.append("--reload")+ if ignored_options:+ logger.warning(+ f"Options {', '.join(ignored_options)} are ignored in module mode "+ f"(-m). The module manages its own server startup."+ )++ # Build environment wrapper if needed+ env_builder = None+ if not skip_env and not is_already_in_uv_subprocess():+ from fastmcp.utilities.mcp_server_config.v1.environments.uv import (+ UVEnvironment,+ )++ env = UVEnvironment(+ python=python,+ dependencies=with_packages or None,+ requirements=with_requirements,+ project=project,+ )+ test_cmd = ["test"]+ if env.build_command(test_cmd) != test_cmd:+ env_builder = env.build_command++ run_module.run_module_command(+ server_spec,+ env_command_builder=env_builder,+ extra_args=list(server_args) if server_args else None,+ )+ return+# Check if we were spawned by uv (or user explicitly set --skip-env)if skip_env or is_already_in_uv_subprocess():skip_env = Truediff --git a/src/fastmcp/cli/run.py b/src/fastmcp/cli/run.pyindex a662c79f3..46cbae3c1 100644--- a/src/fastmcp/cli/run.py+++ b/src/fastmcp/cli/run.py@@ -6,6 +6,7 @@ import jsonimport osimport reimport signal+import subprocessimport sysfrom pathlib import Pathfrom typing import Any, Literal@@ -255,6 +256,41 @@ async def run_command(sys.exit(1)+def run_module_command(+ module_name: str,+ *,+ env_command_builder: Any | None = None,+ extra_args: list[str] | None = None,+) -> None:+ """Run a Python module directly using ``python -m <module>``.++ When ``-m`` is used, the module manages its own server startup.+ No server-object discovery or transport overrides are applied.++ Args:+ module_name: Dotted module name (e.g. ``my_package``).+ env_command_builder: An optional callable that wraps a command list+ with environment setup (e.g. ``UVEnvironment.build_command``).+ extra_args: Extra arguments forwarded after the module name.+ """+ cmd: list[str] = [sys.executable, "-m", module_name]+ if extra_args:+ cmd.extend(extra_args)++ # Wrap with environment (e.g. uv run) if configured+ if env_command_builder is not None:+ cmd = env_command_builder(cmd)++ logger.debug(f"Running module: {' '.join(cmd)}")++ try:+ process = subprocess.run(cmd, check=True)+ sys.exit(process.returncode)+ except subprocess.CalledProcessError as e:+ logger.error(f"Module {module_name} exited with code {e.returncode}")+ sys.exit(e.returncode)++async def run_v1_server_async(server: FastMCP1x,host: str | None = None,diff --git a/tests/cli/test_run.py b/tests/cli/test_run.pyindex 184ea1dde..bcb8e1a78 100644--- a/tests/cli/test_run.py+++ b/tests/cli/test_run.py@@ -695,3 +695,118 @@ class TestReloadFunctionality:}for ext in expected:assert ext in WATCHED_EXTENSIONS, f"Expected {ext} in WATCHED_EXTENSIONS"+++class TestRunModuleCommand:+ """Test run_module_command functionality."""++ def test_runs_python_m_module(self):+ """Test that run_module_command invokes python -m <module>."""+ from unittest.mock import MagicMock, patch++ from fastmcp.cli.run import run_module_command++ mock_result = MagicMock()+ mock_result.returncode = 0++ with (+ patch(+ "fastmcp.cli.run.subprocess.run", return_value=mock_result+ ) as mock_run,+ pytest.raises(SystemExit) as exc_info,+ ):+ run_module_command("my_package")++ assert exc_info.value.code == 0+ call_args = mock_run.call_args+ cmd = call_args[0][0]+ assert "-m" in cmd+ assert "my_package" in cmd++ def test_forwards_extra_args(self):+ """Test that extra arguments are forwarded after the module name."""+ from unittest.mock import MagicMock, patch++ from fastmcp.cli.run import run_module_command++ mock_result = MagicMock()+ mock_result.returncode = 0++ with (+ patch(+ "fastmcp.cli.run.subprocess.run", return_value=mock_result+ ) as mock_run,+ pytest.raises(SystemExit),+ ):+ run_module_command("my_package", extra_args=["--host", "0.0.0.0"])++ cmd = mock_run.call_args[0][0]+ assert "--host" in cmd+ assert "0.0.0.0" in cmd++ def test_uses_env_command_builder(self):+ """Test that env_command_builder wraps the command."""+ from unittest.mock import MagicMock, patch++ from fastmcp.cli.run import run_module_command++ mock_result = MagicMock()+ mock_result.returncode = 0++ def fake_builder(cmd: list[str]) -> list[str]:+ return ["uv", "run", *cmd]++ with (+ patch(+ "fastmcp.cli.run.subprocess.run", return_value=mock_result+ ) as mock_run,+ pytest.raises(SystemExit),+ ):+ run_module_command("my_package", env_command_builder=fake_builder)++ cmd = mock_run.call_args[0][0]+ assert cmd[0] == "uv"+ assert cmd[1] == "run"+ assert "-m" in cmd+ assert "my_package" in cmd++ def test_exits_with_subprocess_error_code(self):+ """Test that non-zero exit codes from the module are propagated."""+ import subprocess+ from unittest.mock import patch++ from fastmcp.cli.run import run_module_command++ with (+ patch(+ "fastmcp.cli.run.subprocess.run",+ side_effect=subprocess.CalledProcessError(42, ["python", "-m", "bad"]),+ ),+ pytest.raises(SystemExit) as exc_info,+ ):+ run_module_command("bad")++ assert exc_info.value.code == 42++ def test_no_env_builder_runs_plain_python(self):+ """Test that without env_command_builder, plain python is used."""+ import sys+ from unittest.mock import MagicMock, patch++ from fastmcp.cli.run import run_module_command++ mock_result = MagicMock()+ mock_result.returncode = 0++ with (+ patch(+ "fastmcp.cli.run.subprocess.run", return_value=mock_result+ ) as mock_run,+ pytest.raises(SystemExit),+ ):+ run_module_command("my_module", env_command_builder=None)++ cmd = mock_run.call_args[0][0]+ assert cmd[0] == sys.executable+ assert cmd[1] == "-m"+ assert cmd[2] == "my_module"