ClaudePlane

MCP server and automation watcher for Plane project management.

Features:

• MCP server providing 40+ tools for Claude to interact with Plane
• Watcher that automatically triggers Claude when issues are labeled or updated
• Self-hosted Plane support
• Single config file for both MCP and watcher

Installation

git clone https://github.com/FishyF1sh/claude-plane.git
cd claude-plane
npm install
npm run build

Quick Start

1. Create config file

In your project directory, create plane.config.json:

{
  "plane": {
    "baseUrl": "https://your-plane-instance.com",
    "apiKey": "plane_api_your-api-key",
    "workspace": "your-workspace",
    "project": "your-project"
  },
  "watch": {
    "pollIntervalSeconds": 30,
    "triggerLabel": "claude",
    "triggers": {
      "onLabelAdded": true,
      "onReopened": true,
      "onNewComment": true
    }
  },
  "claude": {
    "prompt": "/fix-issue {identifiers}"
  }
}

2. Configure Claude Code

Add to ~/.claude.json:

{
  "projects": {
    "/path/to/your/project": {
      "mcpServers": {
        "plane": {
          "type": "stdio",
          "command": "node",
          "args": ["/path/to/claude-plane/dist/index.js"],
          "env": {
            "PLANE_CONFIG": "/path/to/your/project/plane.config.json"
          }
        }
      }
    }
  }
}

3. Control the watcher (optional)

The watcher can be controlled in two ways:

Via MCP tools (recommended): Ask Claude to start/stop the watcher using the built-in tools:

• plane_watcher_start - Start monitoring for labeled issues
• plane_watcher_stop - Stop the watcher
• plane_watcher_status - Check watcher status and logs

Via command line:

cd /path/to/your/project
node /path/to/claude-plane/dist/watcher.js

That's it! Claude can now interact with Plane, and the watcher will auto-trigger Claude on labeled issues.

Configuration Reference

plane.config.json

{
  "plane": {
    "baseUrl": "https://your-plane-instance.com",
    "apiKey": "plane_api_your-api-key",
    "workspace": "your-workspace",
    "project": "your-project"
  },
  "watch": {
    "pollIntervalSeconds": 30,
    "triggerLabel": "claude",
    "triggers": {
      "onLabelAdded": true,
      "onReopened": true,
      "onNewComment": true
    }
  },
  "claude": {
    "prompt": "/fix-issue {identifiers}"
  }
}

Trigger Conditions

Prompt Placeholders

Available MCP Tools

Projects: plane_list_projects, plane_get_project, plane_create_project, plane_update_project, plane_delete_project

Work Items: plane_list_work_items, plane_get_work_item, plane_create_work_item, plane_update_work_item, plane_delete_work_item

Cycles: plane_list_cycles, plane_get_cycle, plane_create_cycle, plane_update_cycle, plane_delete_cycle, plane_add_work_items_to_cycle, plane_remove_work_item_from_cycle

Modules: plane_list_modules, plane_get_module, plane_create_module, plane_update_module, plane_delete_module, plane_add_work_items_to_module, plane_remove_work_item_from_module

States: plane_list_states, plane_create_state, plane_update_state, plane_delete_state

Labels: plane_list_labels, plane_create_label, plane_update_label, plane_delete_label

Comments: plane_list_comments, plane_create_comment, plane_update_comment, plane_delete_comment

Links: plane_list_links, plane_create_link, plane_delete_link

Activities: plane_list_activities

Members: plane_list_workspace_members, plane_list_project_members

Attachments: plane_list_attachments, plane_upload_attachment, plane_delete_attachment

User: plane_get_current_user

Watcher: plane_watcher_start, plane_watcher_stop, plane_watcher_status

Custom Claude Commands

Example commands are included in examples/commands/. To install them:

cp examples/commands/*.md ~/.claude/commands/

Available Commands

fix-issue - Handle Plane issues by implementing fixes, committing changes, and updating issue status.

Usage:

/fix-issue PROJ-123
/fix-issue PROJ-123 PROJ-124

You can customize these commands or create your own based on them.

Backwards Compatibility

The MCP server also supports environment variables instead of a config file:

{
  "env": {
    "PLANE_API_KEY": "plane_api_...",
    "PLANE_BASE_URL": "https://...",
    "PLANE_WORKSPACE_SLUG": "your-workspace"
  }
}

Development

npm run build        # Build
npm start            # Run MCP server
npm run watch        # Run watcher
npm run dev          # Dev mode (MCP)
npm run dev:watch    # Dev mode (watcher)

License

MIT