Plane MCP Server

A Model Context Protocol (MCP) server that enables LLMs to interact with Plane.so, allowing them to manage projects and issues through Plane's API. Using this server, LLMs like Claude can directly interact with your project management workflows while maintaining user control and security.

⚠️ Important: This MCP server is designed specifically for Plane Cloud instances. It only works with workspaces hosted on https://app.plane.so/workspace-slug. If you're using a self-hosted Plane installation, this server will not be compatible.

Note: This is an enhanced fork of the original kelvin6365/plane-mcp-server, extended with comprehensive Plane API functionality including states, modules (sprints), cycles, labels, team management, comments, links, attachments, time tracking, and issue types.

Features

Pagination Support

• Cursor-based pagination for all list operations (projects, issues, modules, cycles, labels)
• Configurable page sizes up to 100 items per page
• Navigation through large datasets with next/previous cursors
• Consistent pagination across all list tools

Project Management

• List all projects in your Plane workspace with pagination
• Get detailed information about specific projects

Issue Management

• Create new issues with customizable properties
• List and filter issues from projects
• Get detailed information about specific issues
• Update existing issues with new information

State Management

• List all states in a project
• Get detailed information about specific states
• Create new states with customizable properties
• Update existing states
• Delete states from projects

Module (Sprint) Management

• List all modules (sprints) in a project
• Get detailed information about specific modules
• Create new modules with customizable properties
• Update existing modules
• Delete modules from projects
• List issues assigned to specific modules
• Add/remove issues to/from modules

Cycle Management

• List all cycles in a project
• Get detailed information about specific cycles
• Create new cycles with customizable properties
• Update existing cycles
• Delete cycles from projects
• List issues assigned to specific cycles
• Add/remove issues to/from cycles

Label Management

• List all labels in a project
• Get detailed information about specific labels
• Create new labels with customizable properties
• Update existing labels
• Delete labels from projects

Team & Workspace Management

• List all members in the workspace
• List members assigned to specific projects

Issue Comments & Communication

• List, create, update, and delete comments on issues
• Track discussion history and collaboration

Issue Links & External References

• Attach external links to issues (documentation, PRs, etc.)
• Manage and update issue-related URLs

File Attachments

• List file attachments for issues
• Generate upload URLs for new attachments

Issue Activity & History

• View complete activity history for issues
• Track all changes and updates

Time Tracking (Worklogs)

• Log time spent on specific issues
• View project-wide time tracking summaries
• Update and manage worklog entries

Custom Issue Types

• Create and manage custom issue types
• Define project-specific issue categories

Intake Issues (Triage)

• Handle intake/inbox issues for triage
• Manage issue submissions before project assignment

Custom Issue Properties

• Create and manage custom properties for issue types
• Support for various property types (text, number, date, options, boolean)
• Configure dropdown options for select properties
• Set required fields and validation rules

Sub-issues & Relations

• Create hierarchical issue structures with parent-child relationships
• Convert existing issues to sub-issues
• List and manage sub-issue trees
• Convert sub-issues back to regular issues

Issue Transfer Operations

• Transfer issues between cycles for better sprint management
• Bulk move issues to different project phases

Prerequisites

• Node.js 22.x or higher
• A Plane.so API key
• A Plane.so workspace

Installation

Option 1: Using NPM (Recommended)

The quickest way to get started is to use the published npm package:

{
  "mcpServers": {
    "plane": {
      "command": "npx",
      "args": [
        "-y",
        "@disrex/plane-mcp-server"
      ],
      "env": {
        "PLANE_API_KEY": "your_plane_api_key_here",
        "PLANE_WORKSPACE_SLUG": "your_workspace_slug_here"
      }
    }
  }
}

Add this configuration to your Claude for Desktop config file:

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

Option 2: Manual Setup

If you prefer to set up the server manually, follow these steps:

1. Clone this repository:

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

1. Install dependencies:

npm install

1. Build the server:

npm run build

Getting Your Plane API Credentials

To use this MCP server, you'll need:

1. Plane API Key: Generate one from your personal settings (not workspace settings) in Plane
2. Workspace Slug: Found in your Plane workspace URL (e.g., https://app.plane.so/workspace-slug/)

After obtaining these credentials, use them in your Claude configuration as shown in the installation options above.

Available Tools

Note: Tool names use hyphens (e.g., list-projects), not underscores. The server will automatically convert underscores to hyphens for compatibility.

list-projects

Lists all projects in your Plane workspace with pagination support.

Parameters:

• per_page (optional): Number of items per page (default: 100, max: 100)
• cursor (optional): Pagination cursor in format 'value:offset:is_prev'

Example:

{
  "per_page": 50
}

Example with pagination:

{
  "per_page": 25,
  "cursor": "project_name:25:false"
}

get-project

Gets detailed information about a specific project.

Parameters:

• project_id: ID of the project to retrieve

Example:

{
  "project_id": "01abc123-4567-89de-0123-456789abcdef"
}

create-issue

Creates a new issue in a specified project.

Parameters:

• project_id: ID of the project where the issue should be created
• name: Title of the issue
• description_html: HTML description of the issue (required by Plane API)
• priority (optional): Priority of the issue ("urgent", "high", "medium", "low", "none")
• state_id (optional): ID of the state for this issue
• assignees (optional): Array of user IDs to assign to this issue
• labels (optional): Array of label IDs to assign to this issue

Note: The assignees and labels parameters must be arrays of ID strings. Common errors include providing a dictionary/object instead of an array, or accidentally nesting the entire issue data inside these fields. The server will attempt to handle these cases, but it's best to use the correct format.

Example:

{
  "project_id": "01abc123-4567-89de-0123-456789abcdef",
  "name": "Implement new feature",
  "description_html": "<p>We need to implement the new reporting feature</p>",
  "priority": "high",
  "assignees": ["user-id-1", "user-id-2"],
  "labels": ["446cf3ad-446e-4b7a-8706-14121a0338d7", "ab0c39d4-dcae-4ccd-971a-f4c66d1e7db7"]
}

list-issues

Lists issues from a specified project with optional filtering and pagination.

Parameters:

• project_id: ID of the project to get issues from
• state_id (optional): Filter by state ID
• priority (optional): Filter by priority
• assignee_id (optional): Filter by assignee ID
• per_page (optional): Number of items per page (default: 100, max: 100)
• cursor (optional): Pagination cursor in format 'value:offset:is_prev'

Examples:

Basic filtering:

{
  "project_id": "01abc123-4567-89de-0123-456789abcdef",
  "priority": "high",
  "per_page": 20
}

With pagination (first page):

{
  "project_id": "01abc123-4567-89de-0123-456789abcdef",
  "per_page": 20
}

With pagination (next page using cursor from previous response):

{
  "project_id": "01abc123-4567-89de-0123-456789abcdef",
  "per_page": 20,
  "cursor": "20:1:0"
}

get-issue

Gets detailed information about a specific issue.

Parameters:

• project_id: ID of the project containing the issue
• issue_id: ID of the issue to retrieve

Example:

{
  "project_id": "01abc123-4567-89de-0123-456789abcdef",
  "issue_id": "01def456-7890-12gh-3456-789ijklmnopq"
}

update-issue

Updates an existing issue in a project.

Parameters:

• project_id: ID of the project containing the issue
• issue_id: ID of the issue to update
• name (optional): Updated title of the issue
• description_html (optional): HTML description of the issue (required by Plane API)
• priority (optional): Updated priority of the issue
• state_id (opti

---