Plane MCP server for AI agents

The Plane MCP Server is a powerful tool that enables AI assistants to interact with the Plane project management platform. It provides functionality for managing workspaces, projects, issues, and more through the Model Context Protocol.

Installation

Prerequisites

Node.js installed on your system
A Plane account with API access
Your Plane API key, base URL, and workspace slug

Setup Steps

Clone the repository:

git clone https://github.com/yourusername/plane-mcp-server.git
cd plane-mcp-server

Install dependencies:
```
npm install
```

Create an environment configuration:

# Create a .env file based on .env.example
cp .env.example .env

Configure your environment variables in the .env file:

PLANE_API_KEY=your_api_key
PLANE_BASE_URL=https://plane.yourdomain.com
PLANE_WORKSPACE_SLUG=your_workspace_slug

Build the TypeScript code:
```
npm run build
```
Start the server:
```
npm start
```

For development with automatic reloading:

npm run dev

Deployment on Smithery.ai

To deploy the MCP server on Smithery.ai:

Log in to Smithery.ai
Follow the platform's instructions to publish your MCP server
Configure the following environment variables:
- PLANE_API_KEY: Your Plane API key
- PLANE_BASE_URL: URL of your Plane instance
- PLANE_WORKSPACE_SLUG: Your workspace slug in Plane

Available Tools

Workspace Management

list-workspaces: Lists all workspaces you have access to
get-workspace: Retrieves details about the current workspace

Project Operations

list-projects: Lists all projects in the workspace
get-project: Retrieves details of a specific project

State Management

get-project-states: Retrieves all states defined in a project

Cycle Operations

list-cycles: Lists all cycles in a project
get-cycle: Retrieves details of a specific cycle

Module Operations

list-modules: Lists all modules in a project
get-module: Retrieves details of a specific module

Issue Management

list-issues: Lists issues in a project with optional filtering
get-issue: Retrieves details of a specific issue
create-issue: Creates a new issue
update-issue: Updates an existing issue
delete-issue: Deletes an issue

Comment Management

list-issue-comments: Lists all comments on an issue
add-issue-comment: Adds a comment to an issue

Usage Examples

Creating a New Issue

To create a new issue in a project:

// Example of using the create-issue tool
const newIssue = {
  name: "Fix login bug",
  description: "Users are experiencing login failures when using Safari",
  project_id: "PROJECT_ID",
  priority: "high",
  state_id: "STATE_ID"
};

// Tool would be called with these parameters

Filtering Issues

To list issues with specific criteria:

// Example of using the list-issues tool with filters
const filters = {
  project_id: "PROJECT_ID",
  priority: "high",
  assignees: ["USER_ID1", "USER_ID2"],
  state_id: "STATE_ID_IN_PROGRESS"
};

// Tool would be called with these parameters

Adding a Comment

To add a comment to an existing issue:

// Example of using the add-issue-comment tool
const comment = {
  issue_id: "ISSUE_ID",
  project_id: "PROJECT_ID",
  comment_html: "<p>This issue should be fixed in the next release.</p>"
};

// Tool would be called with these parameters

How to install this MCP server

For Claude Code

To add this MCP server to Claude Code, run this command in your terminal:

claude mcp add-json "plane" '{"command":"npm","args":["start"],"env":{"PLANE_API_KEY":"","PLANE_BASE_URL":"","PLANE_WORKSPACE_SLUG":""}}'

See the official Claude Code MCP documentation for more details.

For Cursor

There are two ways to add an MCP server to Cursor. The most common way is to add the server globally in the ~/.cursor/mcp.json file so that it is available in all of your projects.

If you only need the server in a single project, you can add it to the project instead by creating or adding it to the .cursor/mcp.json file.

Adding an MCP server to Cursor globally

To add a global MCP server go to Cursor Settings > Tools & Integrations and click "New MCP Server".

When you click that button the ~/.cursor/mcp.json file will be opened and you can add your server like this:

{
    "mcpServers": {
        "plane": {
            "command": "npm",
            "args": [
                "start"
            ],
            "env": {
                "PLANE_API_KEY": "",
                "PLANE_BASE_URL": "",
                "PLANE_WORKSPACE_SLUG": ""
            }
        }
    }
}

Adding an MCP server to a project

To add an MCP server to a project you can create a new .cursor/mcp.json file or add it to the existing one. This will look exactly the same as the global MCP server example above.

How to use the MCP server

Once the server is installed, you might need to head back to Settings > MCP and click the refresh button.

The Cursor agent will then be able to see the available tools the added MCP server has available and will call them when it needs to.

You can also explicitly ask the agent to use the tool by mentioning the tool name and describing what the function does.

For Claude Desktop

To add this MCP server to Claude Desktop:

1. Find your configuration file:

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
Windows: %APPDATA%\Claude\claude_desktop_config.json
Linux: ~/.config/Claude/claude_desktop_config.json

2. Add this to your configuration file:

{
    "mcpServers": {
        "plane": {
            "command": "npm",
            "args": [
                "start"
            ],
            "env": {
                "PLANE_API_KEY": "",
                "PLANE_BASE_URL": "",
                "PLANE_WORKSPACE_SLUG": ""
            }
        }
    }
}

3. Restart Claude Desktop for the changes to take effect