fastmcp/docs/cli/install-mcp.mdx

---
title: Install MCP Servers
sidebarTitle: Install MCPs
description: Install MCP servers into Claude, Cursor, Gemini, and other clients
icon: download
---

import { VersionBadge } from '/snippets/version-badge.mdx'

<VersionBadge version="2.10.3" />

`fastmcp install` registers a server with an MCP client application so the client can launch it automatically. Each MCP client runs servers in its own isolated environment, which means dependencies need to be explicitly declared — you can't rely on whatever happens to be installed locally.

```bash
fastmcp install claude-desktop server.py
fastmcp install claude-code server.py --with pandas --with matplotlib
fastmcp install cursor server.py --with-editable .
```

<Warning>
`uv` must be installed and available in your system PATH. Both Claude Desktop and Cursor run servers in isolated environments managed by `uv`. On macOS, install it globally with Homebrew for Claude Desktop compatibility: `brew install uv`.
</Warning>

## Supported Clients

| Client | Install method |
| ------ | -------------- |
| `claude-code` | Claude Code's built-in MCP management |
| `claude-desktop` | Direct config file modification |
| `cursor` | Deeplink that opens Cursor for confirmation |
| `gemini-cli` | Gemini CLI's built-in MCP management |
| `goose` | Deeplink that opens Goose for confirmation (uses `uvx`) |
| `mcp-json` | Generates standard MCP JSON config for manual use |
| `stdio` | Outputs the shell command to run via stdio |

## Declaring Dependencies

Because MCP clients run servers in isolation, you need to tell the install command what your server needs. There are two approaches:

**Command-line flags** let you specify dependencies directly:

```bash
fastmcp install claude-desktop server.py --with pandas --with "sqlalchemy>=2.0"
fastmcp install cursor server.py --with-editable . --with-requirements requirements.txt
```

**`fastmcp.json`** configuration files declare dependencies alongside the server definition. When you install from a config file explicitly, dependencies are picked up automatically:

```bash
fastmcp install claude-desktop fastmcp.json
```

See [Server Configuration](/deployment/server-configuration) for the full config format.

## Options

| Option | Flag | Description |
| ------ | ---- | ----------- |
| Server Name | `--name`, `-n` | Custom name for the server |
| Editable Package | `--with-editable` | Install a directory in editable mode |
| Extra Packages | `--with` | Additional packages (repeatable) |
| Environment Variables | `--env` | `KEY=VALUE` pairs (repeatable) |
| Environment File | `--env-file` | Load env vars from a `.env` file |
| Python | `--python` | Python version (e.g., `3.11`) |
| Project | `--project` | Run within a uv project directory |
| Requirements | `--with-requirements` | Install from a requirements file |
| Config Path | `--config-path` | Custom path to Claude Desktop config directory (`claude-desktop` only) |
| Workspace | `--workspace` | Install to the workspace directory instead of globally (`cursor` only) |
| Copy | `--copy` | Copy the generated output to the clipboard (`mcp-json` and `stdio` only) |

`goose` installs through a deeplink that runs your server with `uvx`, so it accepts only `--name`, `--with`, and `--python`. Options that depend on a local uv project — `--with-editable`, `--project`, and `--with-requirements` — are unavailable there. Deeplinks also cannot carry environment variables: passing `--env` or `--env-file` exits with an error directing you to `fastmcp install mcp-json`, which generates a config you can add to Goose by hand with the variables included.

## Examples

```bash
# Basic install with auto-detected server instance
fastmcp install claude-desktop server.py

# Install from fastmcp.json
fastmcp install claude-desktop fastmcp.json

# Explicit entrypoint with dependencies
fastmcp install claude-desktop server.py:my_server \
  --name "My Analysis Server" \
  --with pandas

# With environment variables
fastmcp install claude-code server.py \
  --env API_KEY=secret \
  --env DEBUG=true

# With env file
fastmcp install cursor server.py --env-file .env

# Specific Python version and requirements file
fastmcp install claude-desktop server.py \
  --python 3.11 \
  --with-requirements requirements.txt

# With custom config path (claude-desktop only)
fastmcp install claude-desktop server.py \
  --config-path "C:\Users\username\AppData\Local\Packages\Claude_xyz\LocalCache\Roaming\Claude"
```

## Generating MCP JSON

The `mcp-json` target generates standard MCP configuration JSON instead of installing into a specific client. This is useful for clients that FastMCP doesn't directly support, for CI/CD environments, or for sharing server configs:

```bash
fastmcp install mcp-json server.py
```

The output follows the standard format used by Claude Desktop, Cursor, and other MCP clients:

```json
{
  "server-name": {
    "command": "uv",
    "args": ["run", "--with", "fastmcp", "fastmcp", "run", "/path/to/server.py"],
    "env": {
      "API_KEY": "value"
    }
  }
}
```

Use `--copy` to send it to your clipboard instead of stdout.

## Generating Stdio Commands

The `stdio` target outputs the shell command an MCP host would use to start your server over stdio:

```bash
fastmcp install stdio server.py
# Output: uv run --with fastmcp fastmcp run /absolute/path/to/server.py
```

When installing from a `fastmcp.json`, dependencies from the config are included automatically:

```bash
fastmcp install stdio fastmcp.json
# Output: uv run --with fastmcp --with pillow --with 'qrcode[pil]>=8.0' fastmcp run /path/to/server.py
```

Use `--copy` to copy to clipboard.

<Tip>
`fastmcp install` is designed for local server files with stdio transport. For remote servers running over HTTP, use your client's native configuration — FastMCP's value here is simplifying the complex local setup with `uv`, dependencies, and environment variables.
</Tip>