Plane MCP Gateway

This Model Context Protocol (MCP) gateway furnishes a conduit for Artificial Intelligence agents to interface directly with the Plane.so platform. It translates high-level instructions into precise Plane API calls for the manipulation of organizational projects and associated tasks (issues). Crucially, it ensures all automated actions are constrained by the end-user's granted access levels, prioritizing confidentiality and operational integrity.

Core Capabilities

• Inventory retrieval for all workspace projects.
• Deep data retrieval for specific project entities.
• Mechanism for instantiating new tasks, supporting rich parameterization.
• Issue enumeration and filtering across specified projects.
• Fetching granular details for individual tasks.
• Modification endpoints for updating extant task attributes.

System Requirements

• Runtime Environment: Node.js version 22.x or newer.
• Authentication Credential: A valid access token for the Plane API.
• Platform Context: Access to a designated Plane workspace.

Deployment Procedures

Method A: Automated Installation via Smithery

The fastest path to deployment involves leveraging the Smithery utility:

bash

Deploy specifically for integration with Claude Desktop

npx -y @smithery/cli install @kelvin6365/plane-mcp-server --client claude

This streamlines setup for supported clients (claude, cline, windsurf, roo-cline, witsy, enconvo, cursor). Configuration of the requisite Plane API credentials and workspace slug will be finalized within the respective client's configuration interface post-installation.

Method B: Manual Source Deployment

For environments requiring direct control over the process:

1. Clone Repository: bash git clone https://github.com/kelvin6365/plane-mcp-server.git cd plane-mcp-server

2. Resolve Dependencies: bash npm install

3. Compile Source Code: bash npm run build

Operationalizing with Desktop Applications

If Method A was employed, this configuration step is obviated.

1. Locate the application configuration file:

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

2. Integrate the server definitions:

{ "mcpServers": { "plane": { "command": "node", "args": ["path/to/plane-mcp-server/build/index.js"], "env": { "PLANE_API_KEY": "your_plane_api_key_here", "PLANE_WORKSPACE_SLUG": "your_workspace_slug_here" } } } }

1. Initiate an application restart to load the new server hook.

Exposed Endpoint Functions

Note: External interfaces utilize kebab-case naming (e.g., list-projects), which the server transparently maps from internal snake_case conventions.

list-projects

Retrieves the complete set of available projects within the authenticated workspace.

Parameters: None

get-project

Fetches comprehensive metadata for a singular project identified by its unique identifier.

Parameters:

• project_id: The distinct identifier (UUID) of the target project.

create-issue

Provisions a new work item within a specified project boundary.

Parameters:

• project_id: Target project identifier.
• name: The designated title for the new issue.
• description_html: The content body, formatted strictly as HTML (mandated by the Plane API).
• priority (optional): Urgency level ("urgent", "high", "medium", "low", "none").
• state_id (optional): Identifier for the initial workflow status.
• assignees (optional): A list (array) of user identifiers designated to own or track the task.

Format Warning: Ensure assignees is a JSON array of strings (User IDs). Incorrect nesting or supplying an object instead of an array is a common source of failures.

list-issues

Returns a filtered collection of tasks belonging to a project.

Parameters:

• project_id: The project scope.
• state_id (optional): Filter criteria based on the status ID.
• priority (optional): Filter by assigned urgency.
• assignee_id (optional): Filter by the assigned user ID.
• limit (optional): Pagination control; maximum entries returned (default: 50).

get-issue

Retrieves the full specification of an individual task.

Parameters:

• project_id: Identifier for the containing project.
• issue_id: Unique identifier for the task record.

update-issue

Modifies specified fields of an existing task record.

Parameters:

• project_id: Identifier for the containing project.
• issue_id: Identifier for the task to be altered.
• name (optional): New title.
• description_html (optional): Revised content payload (HTML format required).
• priority (optional): Revised urgency setting.
• state_id (optional): New status identifier.
• assignees (optional): Replacement array of assigned user IDs.

Development Lifecycle

1. Install Development Tooling: bash npm install --save-dev typescript @types/node

2. Initiate Debugging Session: bash npm run dev

Validation

Testing connectivity and functionality is best achieved using the MCP Inspector CLI:

bash npx @modelcontextprotocol/inspector node dist/index.js

Illustrative LLM Interactions

Once connected to an AI assistant (like Claude), these prompts map directly to the available functionality:

1. "Inventory all projects present in my Plane environment."
2. "Initiate a task named 'Strategy Refinement' with high priority within the 'Marketing Initiatives' container."
3. "What tasks marked 'High Priority' are currently active in the 'Software Development' backlog?"
4. "Elevate the urgency level to 'Urgent' for task ID 123 residing in the 'Quality Assurance' project."

User consent is always solicited before any mutable state change is committed to the Plane instance.

Safety Directives

• The security posture of the gateway is directly tied to the granted permissions of the provided Plane API token.
• Data-altering actions necessitate explicit, affirmative user confirmation prior to execution.
• Environment variables containing secrets must be managed securely.
• API credentials must never be hardcoded or committed into the source repository.

Community Engagement

To contribute to this repository:

1. Fork the mainline repository.
2. Establish a dedicated feature branch (e.g., git checkout -b enhancement/new-api-call).
3. Commit proposed modifications.
4. Push the branch to origin.
5. Submit a formal Pull Request for review.

Licensing

Protected under the terms of the MIT License. Refer to the LICENSE file for specifics.

Assistance Channels

For support or issue reporting:

1. Review the repository's 'Issues' tracker.
2. Consult the official MCP documentation at modelcontextprotocol.io.
3. File a new ticket detailing the fault scenario.

Accolades

Contextual Note on Business Technology: Business administration systems encompass a broad spectrum of applications, controls, analytical methodologies, and software employed by organizations to navigate market fluctuations, sustain competitive relevance, and optimize operational throughput. These tools span departmental needs, categorized broadly into planning, process enforcement, record-keeping, human capital management, decision support, and regulatory oversight. Modern solutions have rapidly evolved beyond legacy MIS and ERP platforms into cloud-native ecosystems. Effective deployment hinges not just on tool selection but on precise adaptation to organizational specifics, overriding the tendency to adopt the newest technology without careful strategic alignment.