Plane Project Management MCP server

Claudeus Plane MCP is a powerful server that integrates Claude's AI capabilities with Plane's project management platform, creating an automated workflow bridge between AI assistance and project management tasks. The server enables AI-powered project creation, task management, team collaboration, and communication features.

Installation

Prerequisites

Node.js ≥ 22.0.0
TypeScript ≥ 5.0.0
PNPM
Plane instance with API access

Setup Instructions

# Clone the repository
git clone https://github.com/deus-h/claudeus-plane-mcp

# Install dependencies
pnpm install

# Build the project
pnpm build

# Configure Claude Desktop
cp claude_desktop_config.json.example claude_desktop_config.json
# Edit claude_desktop_config.json with your settings

Configuration

# Copy example configs
cp .env.example .env
cp plane-instances.json.example plane-instances.json

# Edit .env and plane-instances.json with your settings

Configuring plane-instances.json

The plane-instances.json file configures your Plane instances for integration:

{
  "instance-alias": {
    "baseUrl": "https://your-plane-instance.com/api/v1",
    "defaultWorkspace": "your-workspace-slug",
    "otherWorkspaces": ["workspace2", "workspace3"],
    "apiKey": "your-plane-api-key"
  }
}

Configuration Fields

• baseUrl: The base URL of your Plane API (required)
• defaultWorkspace: The default workspace slug (required)
• otherWorkspaces: Array of additional workspace slugs (optional)
• apiKey: Your Plane API key (required)

Claude Desktop Integration

Configuration Location

The Claude Desktop configuration file can be found at:

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

⚠️ IMPORTANT: If you already have other MCP servers configured in Claude Desktop, DO NOT directly copy the example file as it will overwrite your existing configuration! Instead:

For existing Claude Desktop users:

• Open your existing config through Claude Desktop
• Add the Claudeus Plane MCP server configuration to your existing mcpServers object

For new Claude Desktop users:

# For macOS
cp claude_desktop_config.json.example ~/Library/Application\ Support/Claude/claude_desktop_config.json

# For Windows (in PowerShell)
Copy-Item claude_desktop_config.json.example $env:APPDATA\Claude\claude_desktop_config.json

Configuration Examples

NPX Setup

{
  "mcpServers": {
    "claudeus-plane-mcp": {
      "command": "npx",
      "args": [
        "-y",
        "claudeus-plane-mcp"
      ],
      "env": {
        "PLANE_INSTANCES_PATH": "/absolute/path/to/your/plane-instances.json"
      }
    }
  }
}

Docker Setup

{
  "mcpServers": {
    "claudeus-plane-mcp": {
      "command": "docker",
      "args": [
        "run",
        "-i",
        "--rm",
        "--network=host",
        "--mount", "type=bind,src=/absolute/path/to/your/plane-instances.json,dst=/app/plane-instances.json",
        "--mount", "type=bind,src=/absolute/path/to/your/.env,dst=/app/.env",
        "mcp/plane",
        "--config", "/app/plane-instances.json"
      ]
    }
  }
}

Pro Tip: Make sure to replace /absolute/path/to/your/plane-instances.json with the actual path to your configuration file!

After Configuration

1. Restart Claude Desktop completely
2. Look for the hammer 🔨 icon in the bottom right corner of the input box
3. Click it to see available Plane management tools

Troubleshooting

If the server isn't showing up in Claude:

• Verify your claude_desktop_config.json syntax
• Ensure file paths are absolute and valid
• Check Claude's logs at:
  • macOS: ~/Library/Logs/Claude
  • Windows: %APPDATA%\Claude\logs

Available Tools

The MCP server provides several categories of tools for interacting with Plane:

Project Management

• claudeus_plane_projects__list: List all projects (Safe)
• claudeus_plane_projects__create: Create new projects (Moderate)
• claudeus_plane_projects__update: Modify projects (Moderate)
• claudeus_plane_projects__delete: Remove projects (High risk)

Task Management

• claudeus_plane_tasks__list: List all tasks (Safe)
• claudeus_plane_tasks__create: Create new tasks (Moderate)
• claudeus_plane_tasks__update: Modify tasks (Moderate)
• claudeus_plane_tasks__delete: Remove tasks (High risk)

User Management

• claudeus_plane_users__list: List all users (Safe)
• claudeus_plane_users__invite: Invite new users (Moderate)
• claudeus_plane_users__update: Modify user roles (Moderate)
• claudeus_plane_users__remove: Remove users (High risk)

Comment Management

• claudeus_plane_comments__list: List all comments (Safe)
• claudeus_plane_comments__create: Create comments (Moderate)
• claudeus_plane_comments__update: Edit comments (Moderate)
• claudeus_plane_comments__delete: Remove comments (High risk)

Known Limitations

Claude Desktop Response Limits

• Issue: Claude Desktop's maximum response length can be reached during complex operations
• Workaround: Configure Claude Desktop to break tasks into smaller batches or use the Inspector UI

Rate Limiting Considerations

• Issue: Plane API has rate limits that might affect bulk operations
• Mitigation: Use batch processing features and implement appropriate delays between requests

Memory Management

• Issue: Large operations can consume significant memory
• Best Practices: Monitor system resources, use pagination for large datasets, and implement cleanup routines

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 "claudeus-plane-mcp" '{"command":"npx","args":["-y","claudeus-plane-mcp"],"env":{"PLANE_INSTANCES_PATH":"/absolute/path/to/your/plane-instances.json"}}'

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": {
        "claudeus-plane-mcp": {
            "command": "npx",
            "args": [
                "-y",
                "claudeus-plane-mcp"
            ],
            "env": {
                "PLANE_INSTANCES_PATH": "/absolute/path/to/your/plane-instances.json"
            }
        }
    }
}

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": {
        "claudeus-plane-mcp": {
            "command": "npx",
            "args": [
                "-y",
                "claudeus-plane-mcp"
            ],
            "env": {
                "PLANE_INSTANCES_PATH": "/absolute/path/to/your/plane-instances.json"
            }
        }
    }
}

3. Restart Claude Desktop for the changes to take effect