> ## Documentation Index
> Fetch the complete documentation index at: https://developers.plane.so/llms.txt
> Use this file to discover all available pages before exploring further.

# MCP server

> Use the Plane MCP server to integrate with Plane

The [Model Context Protocol](https://modelcontextprotocol.io/overview) (MCP) is a
standardized interface that enables AI models to communicate with external tools and
services. The Plane MCP Server enables AI agents to interact with Plane's project
management capabilities through multiple transport methods.

The Plane MCP Server is open source and available on [GitHub](https://github.com/makeplane/plane-mcp-server).

<Note>
  Beta
  The Plane MCP Server is currently in **Beta**. Some aspects of the API may change.
  While MCP is standardized, it is also rapidly evolving. The Plane MCP Server aims to
  provide a stable implementation for developers to build robust AI-powered
  applications. Please send any issues to [support@plane.so](mailto:support@plane.so).
</Note>

## Transport methods

The Plane MCP Server supports multiple transport methods to accommodate different deployment scenarios:

| Transport                                          | Best for                    | Authentication        |
| -------------------------------------------------- | --------------------------- | --------------------- |
| [HTTP with OAuth](#remote-http-with-oauth)         | Cloud users, simplest setup | Browser-based OAuth   |
| [HTTP with PAT Token](#remote-http-with-pat-token) | Automated workflows, CI/CD  | API key in headers    |
| [Local Stdio](#local-stdio-transport)              | Self-hosted Plane instances | Environment variables |
| [SSE (Legacy)](#sse-transport-legacy)              | Existing integrations       | Browser-based OAuth   |

## Remote HTTP with OAuth

The recommended method for connecting to Plane Cloud. Uses browser-based OAuth for authentication.

### Prerequisites

* **Node.js**: Version 22 or later
* **npx**: Comes bundled with npm

### Claude.ai

1. Open **Settings** from the sidebar on the web or desktop app.
2. Scroll to the **Integrations** section and click **Add more**.
3. Enter the Integration URL: `https://mcp.plane.so/http/mcp`
4. Click **Connect** to link your Plane workspace.

### Claude Desktop

Add to your `claude_desktop_config.json`:

```json theme={null}
{
  "mcpServers": {
    "plane": {
      "command": "npx",
      "args": ["mcp-remote@latest", "https://mcp.plane.so/http/mcp"]
    }
  }
}
```

### Cursor

Add to your Cursor MCP configuration:

```json theme={null}
{
  "mcpServers": {
    "plane": {
      "command": "npx",
      "args": ["mcp-remote@latest", "https://mcp.plane.so/http/mcp"]
    }
  }
}
```

### VSCode

Add to your `.vscode/mcp.json` file:

```json theme={null}
{
  "servers": {
    "plane": {
      "command": "npx",
      "args": ["mcp-remote@latest", "https://mcp.plane.so/http/mcp"]
    }
  }
}
```

### Windsurf

1. Press `Ctrl/Cmd + ,` to open Windsurf settings
2. Navigate to **Cascade** > **MCP servers**
3. Select **Add Server** > **Add custom server**
4. Add the following configuration:

```json theme={null}
{
  "mcpServers": {
    "plane": {
      "command": "npx",
      "args": ["-y", "mcp-remote@latest", "https://mcp.plane.so/http/mcp"]
    }
  }
}
```

### Zed

1. Press `Cmd + ,` to open Zed settings
2. Add the following configuration:

```json theme={null}
{
  "context_servers": {
    "plane": {
      "source": "custom",
      "command": "npx",
      "args": ["-y", "mcp-remote@latest", "https://mcp.plane.so/http/mcp"],
      "env": {}
    }
  }
}
```

## Remote HTTP with PAT Token

Use this method when you need header-based authentication, such as in automated workflows or CI/CD pipelines.

### Prerequisites

* **Node.js**: Version 22 or later
* **npx**: Comes bundled with npm
* **Plane API Key**: Generate from your Plane workspace settings

### Configuration

```json theme={null}
{
  "mcpServers": {
    "plane": {
      "command": "npx",
      "args": ["mcp-remote@latest", "https://mcp.plane.so/http/api-key/mcp"],
      "headers": {
        "Authorization": "Bearer <YOUR_API_KEY>",
        "X-Workspace-slug": "<YOUR_WORKSPACE_SLUG>"
      }
    }
  }
}
```

Replace `<YOUR_API_KEY>` with your Plane API key and `<YOUR_WORKSPACE_SLUG>` with your workspace slug.

## Local Stdio transport

Use this method to connect to a self-hosted Plane instance. The Stdio transport runs locally and communicates directly with your Plane API.

### Prerequisites

* **Python**: Version 3.10 or later
* **uvx**: Comes bundled with [uv](https://docs.astral.sh/uv/getting-started/installation/)

You can verify your installation by running:

```bash theme={null}
python --version
uvx --version
```

### Configuration

```json theme={null}
{
  "mcpServers": {
    "plane": {
      "command": "uvx",
      "args": ["plane-mcp-server", "stdio"],
      "env": {
        "PLANE_API_KEY": "<YOUR_API_KEY>",
        "PLANE_WORKSPACE_SLUG": "<YOUR_WORKSPACE_SLUG>",
        "PLANE_BASE_URL": "https://your-plane-instance.com/api"
      }
    }
  }
}
```

### Environment variables

| Variable               | Required | Description                                                            |
| ---------------------- | -------- | ---------------------------------------------------------------------- |
| `PLANE_API_KEY`        | Yes      | Your Plane API key                                                     |
| `PLANE_WORKSPACE_SLUG` | Yes      | Your workspace slug                                                    |
| `PLANE_BASE_URL`       | No       | API URL for self-hosted instances (defaults to `https://api.plane.so`) |

## SSE transport (Legacy)

<Note>
  The SSE transport is maintained for backward compatibility. For new integrations, we recommend using the [HTTP with OAuth](#remote-http-with-oauth) transport.
</Note>

### Prerequisites

* **Node.js**: Version 22 or later
* **npx**: Comes bundled with npm

### Configuration

```json theme={null}
{
  "mcpServers": {
    "plane": {
      "command": "npx",
      "args": ["mcp-remote@latest", "https://mcp.plane.so/sse"]
    }
  }
}
```

## Activating the Plane MCP Server

After setup, when activating the server with OAuth-based transports (HTTP with OAuth or SSE), you will be prompted in your browser to connect your Plane workspace to the MCP server.

When prompted to authorize, click **Approve**.

Next, choose the workspace you want to connect, review the permissions, and click **Accept**.

## Troubleshooting

### Common issues

**Authentication errors**

If you encounter authentication issues with OAuth transports, clear saved auth tokens:

```bash theme={null}
rm -rf ~/.mcp-auth
```

**Connection timeouts**

* Ensure you have a stable internet connection
* Check if your firewall or proxy is blocking MCP connections
* Verify your Plane instance is accessible

**WSL on Windows**

If you're using WSL on Windows and encountering errors with remote transports:

```json theme={null}
{
  "mcpServers": {
    "plane": {
      "command": "wsl",
      "args": ["npx", "-y", "mcp-remote@latest", "https://mcp.plane.so/http/mcp"]
    }
  }
}
```

**Node.js version**

Ensure you have Node.js 22 or later installed for remote transports.

**Python version**

Ensure you have Python 3.10 or later installed for the local Stdio transport.

### Getting help

If you continue to experience issues:

1. Verify your authentication credentials
2. Contact support at [support@plane.so](mailto:support@plane.so) for Plane-specific issues
3. Check the [MCP community forums](https://modelcontextprotocol.io) for general MCP issues

## Congrats!

You have successfully connected your Plane workspace to the MCP server!