Plane Mcp Server

Plane MCP Server

[](https://badge.fury.io/js/@disrex%2Fplane-mcp-server) [](https://www.archestra.ai/mcp-catalog/server/plane-mcp-server) [](https://opensource.org/licenses/MIT) [](https://github.com/disrex-group/plane-mcp-server/actions/workflows/nodejs-ci.yml) [](https://www.typescriptlang.org/) [](https://plane.so) [](https://modelcontextprotocol.io)

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": "We need to implement the new reporting feature",
  "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 (optional): Updated state ID of the issue
• assignees (optional): Updated array of user IDs to assign to this issue
• labels (optional): Updated array of label IDs to assign to this issue

> Note: The assignees and labels parameters must be arrays of ID strings, following the same format guidelines as the create-issue tool.

Example:

{
  "project_id": "01abc123-4567-89de-0123-456789abcdef",
  "issue_id": "01def456-7890-12gh-3456-789ijklmnopq",
  "priority": "urgent",
  "description_html": "Updated description with more details",
  "labels": ["446cf3ad-446e-4b7a-8706-14121a0338d7", "7de2b3d1-ae1a-4651-a3df-717629d70c1a"]
}

State Management Tools

list-states

Lists all states in a project.

Parameters:

• project_id: ID of the project to get states from

Example:

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

get-state

Gets detailed information about a specific state.

Parameters:

• project_id: ID of the project containing the state
• state_id: ID of the state to retrieve

Example:

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

create-state

Creates a new state in a project.

Parameters:

• project_id: ID of the project where the state should be created
• name: Name of the state
• group: State group ("unstarted", "started", "completed", "cancelled")
• description (optional): Description of the state
• color (optional): Color code for the state (e.g., "#ff0000")

Example:

{
  "project_id": "01abc123-4567-89de-0123-456789abcdef",
  "name": "In Review",
  "group": "started",
  "description": "Issues currently under review",
  "color": "#ffaa00"
}

update-state

Updates an existing state in a project.

Parameters:

• project_id: ID of the project containing the state
• state_id: ID of the state to update
• name (optional): Updated name of the state
• description (optional): Updated description of the state
• color (optional): Updated color code for the state
• group (optional): Updated state group

Example:

{
  "project_id": "01abc123-4567-89de-0123-456789abcdef",
  "state_id": "01def456-7890-12gh-3456-789ijklmnopq",
  "name": "Code Review",
  "color": "#00ff00"
}

delete-state

Deletes a state from a project.

Parameters:

• project_id: ID of the project containing the state
• state_id: ID of the state to delete

Example:

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

Module (Sprint) Management Tools

list-modules

Lists all modules (sprints) in a project with pagination support.

Parameters:

• project_id: ID of the project to get modules from
• per_page (optional): Number of items per page (default: 100, max: 100)
• cursor (optional): Pagination cursor in format 'value:offset:is_prev'

Example:

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

Example with pagination:

{
  "project_id": "01abc123-4567-89de-0123-456789abcdef",
  "per_page": 25,
  "cursor": "module_name:25:false"
}

get-module

Gets detailed information about a specific module.

Parameters:

• project_id: ID of the project containing the module
• module_id: ID of the module to retrieve

Example:

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

create-module

Creates a new module (sprint) in a project.

Parameters:

• project_id: ID of the project where the module should be created
• name: Name of the module
• description (optional): Description of the module
• start_date (optional): Start date of the module (YYYY-MM-DD format)
• target_date (optional): Target end date of the module (YYYY-MM-DD format)
• status (optional): Status of the module ("planned", "in-progress", "paused", "completed", "cancelled")
• lead (optional): User ID of the module lead
• members (optional): Array of user IDs to assign as module members

Example:

{
  "project_id": "01abc123-4567-89de-0123-456789abcdef",
  "name": "Sprint 1 - Core Features",
  "description": "Initial sprint focusing on core functionality",
  "start_date": "2024-01-01",
  "target_date": "2024-01-14",
  "status": "planned",
  "lead": "user-id-1",
  "members": ["user-id-1", "user-id-2"]
}

update-module

Updates an existing module in a project.

Parameters:

• project_id: ID of the project containing the module
• module_id: ID of the module to update
• name (optional): Updated name of the module
• description (optional): Updated description of the module
• start_date (optional): Updated start date of the module
• target_date (optional): Updated target end date of the module
• status (optional): Updated status of the module
• lead (optional): Updated user ID of the module lead
• members (optional): Updated array of user IDs for module members

Example:

{
  "project_id": "01abc123-4567-89de-0123-456789abcdef",
  "module_id": "01def456-7890-12gh-3456-789ijklmnopq",
  "status": "in-progress",
  "target_date": "2024-01-21"
}

delete-module

Deletes a module from a project.

Parameters:

• project_id: ID of the project containing the module
• module_id: ID of the module to delete

Example:

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

list-module-issues

Lists all issues in a specific module.

Parameters:

• project_id: ID of the project containing the module
• module_id: ID of the module to get issues from

Example:

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

add-issues-to-module

Adds issues to a module.

Parameters:

• project_id: ID of the project containing the module
• module_id: ID of the module to add issues to
• issues: Array of issue IDs to add to the module

Example:

{
  "project_id": "01abc123-4567-89de-0123-456789abcdef",
  "module_id": "01def456-7890-12gh-3456-789ijklmnopq",
  "issues": ["issue-id-1", "issue-id-2", "issue-id-3"]
}

remove-issue-from-module

Removes an issue from a module.

Parameters:

• project_id: ID of the project containing the module
• module_id: ID of the module to remove issue from
• issue_id: ID of the issue to remove from the module

Example:

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

…

## Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [disrex-group](https://github.com/disrex-group)
- **Source:** [disrex-group/plane-mcp-server](https://github.com/disrex-group/plane-mcp-server)
- **License:** MIT

Install and usage instructions live in the source repository linked above.