Skip to content

πŸš€ The fast, Pythonic way to build MCP servers and clients.

Clarify Python projects and Cursor workspaces in install docs (#5475)

Andrei Vincea1aa6bf98d32
diff --git a/docs/integrations/claude-desktop.mdx b/docs/integrations/claude-desktop.mdx
index b0d1b5265..8baf6db3d 100644
--- a/docs/integrations/claude-desktop.mdx
+++ b/docs/integrations/claude-desktop.mdx
@@ -80,6 +80,8 @@ After installation, restart Claude Desktop completely. You should see a hammer i
FastMCP provides several ways to manage your server's dependencies when installing in Claude Desktop:
+If your server declares its dependencies in `pyproject.toml`, use the [`--project` option](#python-version-and-project-directory) to select that Python project.
+
**Individual packages**: Use the `--with` flag to specify packages your server needs. You can use this flag multiple times:
```bash
@@ -124,13 +126,13 @@ FastMCP allows you to control the Python environment for your server:
fastmcp install claude-desktop server.py --python 3.11
```
-**Project directory**: Use `--project` to run your server within a specific project directory. This ensures that `uv` will discover all `pyproject.toml`, `uv.toml`, and `.python-version` files from that project:
+**Project directory**: Use `--project` to select the directory containing your MCP server's `pyproject.toml`. FastMCP passes this to `uv run --project`, which discovers the project's configuration and installs its dependencies into the project environment:
```bash
-fastmcp install claude-desktop server.py --project /path/to/my-project
+fastmcp install claude-desktop /path/to/mcp-server/server.py --project /path/to/mcp-server
```
-When you specify a project directory, all relative paths in your server will be resolved from that directory, and the project's virtual environment will be used.
+`--project` selects the Python environment without changing the server's working directory. If your server reads local files, use absolute paths or resolve them relative to the server file.
#### Environment Variables
@@ -296,4 +298,3 @@ proxy = create_proxy(client, name="Authenticated Proxy")
if __name__ == "__main__":
proxy.run()
```
-
diff --git a/docs/integrations/cursor.mdx b/docs/integrations/cursor.mdx
index 787497b02..1aec1920a 100644
--- a/docs/integrations/cursor.mdx
+++ b/docs/integrations/cursor.mdx
@@ -80,6 +80,8 @@ After running the command, Cursor will open automatically and prompt you to inst
FastMCP offers multiple ways to manage dependencies for your Cursor servers:
+If your server declares its dependencies in `pyproject.toml`, use the [`--project` option](#python-version-and-project-configuration) to select that Python project.
+
**Individual packages**: Use the `--with` flag to specify packages your server needs. You can use this flag multiple times:
```bash
@@ -124,12 +126,22 @@ Control your server's Python environment with these options:
fastmcp install cursor server.py --python 3.11
```
-**Project directory**: Use `--project` to run your server within a specific project context. This ensures `uv` discovers all project configuration files and uses the correct virtual environment:
+**Project directory**: Use `--project` to select the directory containing your MCP server's `pyproject.toml`. FastMCP passes this to `uv run --project`, which discovers the project's configuration and installs its dependencies into the project environment:
+
+```bash
+fastmcp install cursor /path/to/mcp-server/server.py --project /path/to/mcp-server
+```
+
+`--project` selects the server's Python environment. [`--workspace`](#workspace-installation) selects the Cursor workspace where FastMCP writes `.cursor/mcp.json`. Use both when your MCP server and editor workspace live in different directories:
```bash
-fastmcp install cursor server.py --project /path/to/my-project
+fastmcp install cursor /path/to/mcp-server/server.py \
+ --project /path/to/mcp-server \
+ --workspace /path/to/editor-workspace
```
+`--project` does not change the server's working directory. If your server reads local files, use absolute paths or resolve them relative to the server file.
+
#### Environment Variables
<Warning>