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

• Plane Documentation
• Plane GitHub
• MCP Documentation
• Cline Documentation

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!