plane-mcp

alanflanders/plane-mcp

3.2

If you are the rightful owner of plane-mcp and would like to certify it and/or have it hosted online, please leave a comment on the right or send an email to dayong@mcphub.com.

A Model Context Protocol (MCP) server for Plane, an open-source project management tool, enabling AI assistants to interact with Plane instances for issue management.

Tools
8
Resources
0
Prompts
0

Plane MCP Server

A Model Context Protocol (MCP) server for Plane, the open-source project management tool. This server enables AI assistants like Cline to interact with your self-hosted Plane instance to create, manage, and search issues.

Perfect for Knowledge Management

This server is ideal for developers who want to:

  • 📝 Document problems and solutions while coding
  • 🔍 Build a searchable knowledge base of past fixes
  • 📊 Track learning progress and technical challenges
  • 🏷️ Organize issues with labels and priorities
  • 🔄 Keep a history of bugs solved and features implemented

Prerequisites

  • Node.js (v18 or later)
  • A running Plane instance (Docker setup included)
  • Plane API key (generated from your Plane account)

Installation

Step 1: Set up Plane (if not already done)

The Plane instance is already installed in ../plane-selfhost. To start it:

cd ../plane-selfhost
bash setup.sh
# Select option 2 to start Plane

Plane will be accessible at http://localhost:8010

Step 2: Create Your Plane Account

  1. Open http://localhost:8010 in your browser
  2. Complete the initial setup form (name, email, company, password)
  3. Create a workspace and project

Step 3: Generate API Key

  1. Log into your Plane instance
  2. Click your profile icon → Profile Settings
  3. Go to Personal Access Tokens tab
  4. Click Add personal access token
  5. Give it a name (e.g., "MCP Server") and optionally set an expiry
  6. Click Add personal access token
  7. Copy the generated API key (you won't see it again!)

Step 4: Configure the MCP Server

  1. Copy the example environment file:

    cp .env.example .env

  2. Edit .env and add your configuration:

    PLANE_URL=http://localhost:8010
PLANE_API_KEY=your_api_key_here
PLANE_WORKSPACE=your-workspace-slug

    To find your workspace slug:

    • In Plane, look at the URL when viewing your workspace
    • It's the part after / (e.g., http://localhost/my-workspace → slug is my-workspace)

Step 5: Add to Cline MCP Configuration

Add this server to your Cline MCP settings file:

Windows: %APPDATA%\Code\User\globalStorage\saoudrizwan.claude-dev\settings\cline_mcp_settings.json

macOS/Linux: ~/.config/Code/User/globalStorage/saoudrizwan.claude-dev/settings/cline_mcp_settings.json

Add the following to the mcpServers object:

{
  "mcpServers": {
    "plane-mcp": {
      "command": "node",
      "args": ["C:\\Users\\alan\\code\\linear-mcp\\plane-mcp-server.js"],
      "disabled": false,
      "alwaysAllow": []
    }
  }
}

Replace the path with the actual path to your plane-mcp-server.js file.

Step 6: Restart Cline

Restart VS Code or reload Cline for the MCP server to be recognized.

Available Tools

🏢 Workspace & Project Management

  • get_workspaces - List all workspaces you have access to
  • get_projects - List all projects in a workspace

📝 Issue Management

  • create_issue - Create a new issue

    • Required: project_id, title
    • Optional: description, priority, state_id, assignee_ids, label_ids, workspace_slug

  • get_issues - List issues from a project

    • Required: project_id
    • Optional: state, priority, assignee, labels, workspace_slug

  • get_issue - Get detailed information about a specific issue

    • Required: project_id, issue_id
    • Optional: workspace_slug

  • update_issue - Update an existing issue

    • Required: project_id, issue_id
    • Optional: title, description, priority, state_id, workspace_slug

  • add_comment - Add a comment to an issue

    • Required: project_id, issue_id, comment
    • Optional: workspace_slug

  • search_issues - Search for issues using text query

    • Required: query
    • Optional: project_id, workspace_slug

Usage Examples

Example Workflow: Documenting a Bug Fix

You: "I just fixed a bug with async timeouts. Document it in Plane."

Cline: [Uses create_issue]
Title: "Fixed async timeout in data fetcher"
Description: "Problem: Async calls were timing out after 5s
Solution: Added configurable timeout parameter with default of 30s
Code: Updated fetchData() function in utils/api.js"
Priority: medium
Labels: ["bug-fix", "async", "solved"]

---

3 weeks later...

You: "How did I fix that async timeout issue?"

Cline: [Uses search_issues with query "async timeout"]
Found issue: "Fixed async timeout in data fetcher"
[Shows full description with solution]

Example: Creating an Issue

Ask Cline:

"Create a Plane issue to document how I fixed the authentication bug. 
Title: Fixed JWT token expiration handling
Description: Added refresh token logic that automatically renews tokens before expiry"

Example: Searching Past Solutions

Ask Cline:

"Search my Plane issues for anything related to database connection pooling"

Example: Listing Projects

Ask Cline:

"Show me all my Plane projects"

Best Practices

  1. Use Labels: Tag issues with technology, type, or topic (e.g., "python", "bug-fix", "optimization")
  2. Write Detailed Descriptions: Include problem context, solution, and code snippets
  3. Set Priorities: Use priority levels to indicate complexity or importance
  4. Regular Documentation: Create issues as you solve problems, while details are fresh
  5. Descriptive Titles: Make titles searchable and clear

Troubleshooting

Server won't start

  • Check that .env file exists and has correct values
  • Verify Plane is running: docker ps should show Plane containers
  • Ensure API key is valid (regenerate if needed)

"workspace_slug is required" error

  • Add PLANE_WORKSPACE to your .env file, OR
  • Include workspace_slug in each request

API authentication errors

  • Regenerate your API key in Plane
  • Update .env with the new key
  • Restart Cline

Cannot find issues

  • Verify you're using the correct project_id
  • Check that issues exist in that project
  • Ensure your API key has access to the project

Project Structure

linear-mcp/
├── plane-mcp-server.js    # Main MCP server implementation
├── package.json           # Node.js dependencies
├── .env.example          # Example environment configuration
├── .env                  # Your actual configuration (not in git)
└── README.md            # This file

Security Notes

  • Never commit .env - It contains your API key
  • Store API keys securely
  • Use appropriate token expiration dates
  • Consider creating separate API keys for different purposes

Related Resources

License

MIT License - Feel free to modify and use as needed.

Contributing

This is a personal tool, but feel free to fork and customize for your needs!