π The fast, Pythonic way to build MCP servers and clients.
feat: Add --workspace flag to fastmcp install cursor (#1522)
Jeremiah Lowin108ad4b70d9c
diff --git a/docs/integrations/cursor.mdx b/docs/integrations/cursor.mdxindex 4d444ab93..e353a4b72 100644--- a/docs/integrations/cursor.mdx+++ b/docs/integrations/cursor.mdx@@ -47,6 +47,21 @@ The easiest way to install a FastMCP server in Cursor is using the `fastmcp instfastmcp install cursor server.py```+#### Workspace Installation+<VersionBadge version="2.12.0" />++By default, FastMCP installs servers globally for Cursor. You can also install servers to project-specific workspaces using the `--workspace` flag:++```bash+# Install to current directory's .cursor/ folder+fastmcp install cursor server.py --workspace .++# Install to specific workspace+fastmcp install cursor server.py --workspace /path/to/project+```++This creates a `.cursor/mcp.json` configuration file in the specified workspace directory, allowing different projects to have their own MCP server configurations.+The install command supports the same `file.py:object` notation as the `run` command. If no object is specified, it will automatically look for a FastMCP server object named `mcp`, `server`, or `app` in your file:```bashdiff --git a/src/fastmcp/cli/install/cursor.py b/src/fastmcp/cli/install/cursor.pyindex 87527ce73..fd252bf23 100644--- a/src/fastmcp/cli/install/cursor.py+++ b/src/fastmcp/cli/install/cursor.py@@ -9,7 +9,7 @@ from typing import Annotatedimport cycloptsfrom rich import print-from fastmcp.mcp_config import StdioMCPServer+from fastmcp.mcp_config import StdioMCPServer, update_config_filefrom fastmcp.utilities.logging import get_loggerfrom .shared import process_common_args@@ -64,6 +64,106 @@ def open_deeplink(deeplink: str) -> bool:return False+def install_cursor_workspace(+ file: Path,+ server_object: str | None,+ name: str,+ workspace_path: Path,+ *,+ with_editable: Path | None = None,+ with_packages: list[str] | None = None,+ env_vars: dict[str, str] | None = None,+ python_version: str | None = None,+ with_requirements: Path | None = None,+ project: Path | None = None,+) -> bool:+ """Install FastMCP server to workspace-specific Cursor configuration.++ Args:+ file: Path to the server file+ server_object: Optional server object name (for :object suffix)+ name: Name for the server in Cursor+ workspace_path: Path to the workspace directory+ with_editable: Optional directory to install in editable mode+ with_packages: Optional list of additional packages to install+ env_vars: Optional dictionary of environment variables+ python_version: Optional Python version to use+ with_requirements: Optional requirements file to install from+ project: Optional project directory to run within++ Returns:+ True if installation was successful, False otherwise+ """+ # Ensure workspace path is absolute and exists+ workspace_path = workspace_path.resolve()+ if not workspace_path.exists():+ print(f"[red]Workspace directory does not exist: {workspace_path}[/red]")+ return False++ # Create .cursor directory in workspace+ cursor_dir = workspace_path / ".cursor"+ cursor_dir.mkdir(exist_ok=True)++ config_file = cursor_dir / "mcp.json"++ # Build uv run command+ args = ["run"]++ # Add Python version if specified+ if python_version:+ args.extend(["--python", python_version])++ # Add project if specified+ if project:+ args.extend(["--project", str(project)])++ # Collect all packages in a set to deduplicate+ packages = {"fastmcp"}+ if with_packages:+ packages.update(pkg for pkg in with_packages if pkg)++ # Add all packages with --with+ for pkg in sorted(packages):+ args.extend(["--with", pkg])++ if with_editable:+ args.extend(["--with-editable", str(with_editable)])++ if with_requirements:+ args.extend(["--with-requirements", str(with_requirements)])++ # Build server spec from parsed components+ if server_object:+ server_spec = f"{file.resolve()}:{server_object}"+ else:+ server_spec = str(file.resolve())++ # Add fastmcp run command+ args.extend(["fastmcp", "run", server_spec])++ # Create server configuration+ server_config = StdioMCPServer(+ command="uv",+ args=args,+ env=env_vars or {},+ )++ try:+ # Create the config file if it doesn't exist+ if not config_file.exists():+ config_file.write_text('{"mcpServers": {}}')++ # Update configuration with the new server+ update_config_file(config_file, name, server_config)+ print(+ f"[green]Successfully installed '{name}' to workspace at {workspace_path}[/green]"+ )+ return True+ except Exception as e:+ print(f"[red]Failed to install server to workspace: {e}[/red]")+ return False++def install_cursor(file: Path,server_object: str | None,@@ -75,6 +175,7 @@ def install_cursor(python_version: str | None = None,with_requirements: Path | None = None,project: Path | None = None,+ workspace: Path | None = None,) -> bool:"""Install FastMCP server in Cursor.@@ -88,6 +189,7 @@ def install_cursor(python_version: Optional Python version to usewith_requirements: Optional requirements file to install fromproject: Optional project directory to run within+ workspace: Optional workspace directory for project-specific installationReturns:True if installation was successful, False otherwise@@ -127,6 +229,21 @@ def install_cursor(# Add fastmcp run commandargs.extend(["fastmcp", "run", server_spec])+ # If workspace is specified, install to workspace-specific config+ if workspace:+ return install_cursor_workspace(+ file=file,+ server_object=server_object,+ name=name,+ workspace_path=workspace,+ with_editable=with_editable,+ with_packages=with_packages,+ env_vars=env_vars,+ python_version=python_version,+ with_requirements=with_requirements,+ project=project,+ )+# Create server configurationserver_config = StdioMCPServer(command="uv",@@ -211,6 +328,13 @@ async def cursor_command(help="Run the command within the given project directory",),] = None,+ workspace: Annotated[+ Path | None,+ cyclopts.Parameter(+ "--workspace",+ help="Install to workspace directory (will create .cursor/ inside it) instead of using deeplink",+ ),+ ] = None,) -> None:"""Install an MCP server in Cursor.@@ -231,6 +355,7 @@ async def cursor_command(python_version=python,with_requirements=with_requirements,project=project,+ workspace=workspace,)if not success:diff --git a/tests/cli/test_cursor.py b/tests/cli/test_cursor.pyindex de52f17e1..87145eac8 100644--- a/tests/cli/test_cursor.py+++ b/tests/cli/test_cursor.py@@ -330,6 +330,7 @@ class TestCursorCommand:python_version=None,with_requirements=None,project=None,+ workspace=None,)mock_exit.assert_not_called()