# Plane MCP

> Plane MCP Server gives your AI client direct read access to your entire Plane workspace. It lets your agent autonomously pull project architectures, list active sprints (`list_cycles`), track every work item/issue (`list_work_items`), and map out the full module taxonomy without you touching a kanban board.

## Overview
- **Category:** productivity
- **Price:** Free
- **Tags:** agile, issue-tracking, kanban, sprint-management, open-source, software-engineering

## Description

This server gives your AI client direct read access to everything in your Plane workspace. Your agent can pull structured data—projects, cycles, issues, modules, and labels—allowing it to analyze complex agile pipelines on demand. You won't need to click through kanban boards or run manual exports anymore; your agent handles the heavy lifting.

### Discovering Your Scope

You start by needing a map of where you are working. Use the `list_projects` tool, and your AI client gets a structured list of every project in your account. If you need to know how issues are grouped across the board, run `list_labels` to pull all available category labels defined throughout your workspace. These tools give you the full context needed before digging into any specific work.

### Deep Project Details and Architecture

Once you've scoped out a project using `list_projects`, you can drill down with `get_project`. This tool extracts detailed data parameters, descriptions, and core metrics for that single Plane project. For understanding the overall architecture, your agent executes `list_modules` to find all major feature groupings or epics assigned to the scope. You'll get a clear view of how the main components relate to one another.

### Tracking Work Status and Timelines

To see what's happening right now, your agent checks the timeline using `list_cycles`. This tool lists all current development cycles—or sprints—and reports their expected completion statuses. When you need to know exactly what tasks are moving through the pipeline, run `list_work_items`. This pulls a comprehensive, structured report of every task and issue within that designated project scope, detailing its status and content. You'll see everything your team's building.

### Running Your Agent

Your AI client uses these tools to build an actionable picture of the entire workspace. It doesn't just pull lists; it builds relationships—mapping how labels define modules, which relate to projects that are currently in a specific development cycle, and finally leading down to the individual work items themselves. You don't need to manually cross-reference anything. Just point your agent at the goal, and it pulls the necessary data points from `list_projects`, `get_project`, `list_cycles`, `list_modules`, `list_labels`, and `list_work_items` to give you a full picture of progress.

## Tools

### get_project
Retrieves detailed data for a specific Plane project using its unique ID.

### list_cycles
Lists all active development cycles (sprints) associated with a given project.

### list_labels
Pulls a list of all available category labels defined in your Plane workspace.

### list_modules
Retrieves the major feature groupings (modules/epics) related to a specific project.

### list_projects
Lists all available projects across your entire Plane workspace, allowing you to find the correct scope.

### list_work_items
Retrieves a list of specific tasks or issues within a project, detailing their status and content.

## Prompt Examples

**Prompt:** 
```
List all cross-functional modules targeting project `project-x`.
```

**Response:** 
```
Pinging standard workspace schemas... I matched Project 'Frontend Rewrite'. There are 4 distinct modules attached: `Auth Module`, `Kanban Redesign`, `API Rate Limiter`, and `User Onboarding`. Looking at `Auth Module`, it is targeting completion by October 20th. Do you need its related tags?
```

**Prompt:** 
```
Are there any pending work items left in the current active active sprint?
```

**Response:** 
```
Looking at cycle `v1.2 Release`, I've pulled 4 unresolved work items out of the 15 originally mapped. Ticket `ID: 9912` (Database Race Condition) is holding up priority, currently marked 'In Progress' by the QA tag. Want me to investigate its raw configuration?
```

**Prompt:** 
```
Fetch the exact details of the issue designated ID `3841-A` on the board.
```

**Response:** 
```
Extracted the data entity mapped to `3841-A`. Title: `Handle missing env parameters explicitly during build steps`. It carries the labels 'High Priority' and 'DevOps'. The raw issue content requests adding an abort sequence checking for missing variables natively during CI initialization. How would you like me to script this?
```

## Capabilities

### Discover all available workspaces
Runs the `list_projects` tool to retrieve a structured list of every project within your Plane account.

### Get detailed info on one project
Uses `get_project` to extract specific data parameters and descriptions for a single, named Plane project.

### Audit sprint timelines
Invokes the `list_cycles` tool to list all current development cycles and their expected completion statuses.

### Trace issue status in depth
Runs `list_work_items` to pull a comprehensive, structured report of all tasks and tickets within a designated project scope.

### Map feature groupings (Epics)
Executes `list_modules` to find the main module groups or epics assigned to a specific project.

### Understand project taxonomy
Retrieves categorization data by listing all available labels (`list_labels`) across your workspace, clarifying how issues are grouped.

## Use Cases

### Need a sprint status report for leadership.
A PM needs to know if the current development cycle is blocked. They ask their agent: 'Check active issues in Project X.' The agent runs `list_work_items` and `list_cycles`, immediately identifying 3 unresolved tickets and flagging the oldest one, saving hours of manual status gathering.

### Writing a feature that needs multiple components.
A Lead Engineer is starting a new task. They ask: 'What modules does Project Y contain?' The agent runs `list_modules`, returning the list (e.g., Auth, API Gateway). The engineer then uses this structured data to write code for all dependencies in sequence.

### Finding out which features are tied to a specific label.
A Product Team member needs to see every task marked 'High Priority'. They ask the agent to list work items filtered by that label. The agent runs `list_work_items` and filters by the label, giving them a complete, sorted inventory without using the visual filter UI.

### Quickly onboarding a new team member.
A manager asks: 'List all projects in the workspace.' The agent runs `list_projects`, providing an immediate, clean list of every active initiative. They can then follow up with `get_project` on any specific project name.

## Benefits

- Stop manually checking the board. Using `list_work_items` lets your agent pull a clean, actionable list of every ticket—status, assignee, description—in one shot.
- Know exactly where things stand in development. Run `list_cycles` to see active sprints and their target completion dates without navigating the calendar view.
- Pinpoint architectural scope instantly. By running `list_modules`, you get a structured breakdown of project epics, letting you cross-reference requirements against the actual plan.
- Audit your entire system structure. Combine `list_projects` with `list_labels` to see every workspace and what categories they use, giving a full organizational picture.
- Validate technical dependencies. Use `get_project` to get core entity details, then run `list_work_items` to see which specific tasks rely on that project's completion.

## How It Works

The bottom line is: your agent treats Plane like a database, not a visual board. It pulls clean JSON outputs for analysis.

1. Install the Plane integration layer onto your agent's setup.
2. Supply your Personal API Key (and self-hosted URL if necessary).
3. Your AI client sends a prompt, and the server runs the required tool calls—like `list_work_items` or `list_cycles`—to return structured data directly to the chat.

## Frequently Asked Questions

**How does I use `list_work_items` with a specific project?**
You must reference the Project ID first. Ask your agent: 'Run `list_work_items` for Project ABC.' The tool then pulls all tickets and issues linked to that single scope.

**Can I find out which projects exist using Plane MCP Server?**
Yes. Use the `list_projects` tool. It runs against your workspace and gives you a master list of every project title and ID available for subsequent queries.

**What is the difference between `list_modules` and `list_labels`?**
Modules are large, structural groupings (Epics) that define major deliverables. Labels are smaller, flexible tags used to categorize items by type or priority (e.g., 'Bug', 'High Priority').

**How do I check the status of the current sprint?**
Use `list_cycles`. This tool lists all active sprints and provides their timeline data, letting you see which cycle is currently running and when it was expected to finish.

**What credentials must I use when calling `get_project`?**
You need a valid Plane Personal API Key or your self-hosted URL. The agent uses this key to authenticate the connection and scope the request directly to your workspace data.

**Can I filter issues when running `list_work_items`?**
Yes, you can pass filters like status or module IDs. This limits the output dramatically, allowing you to check specific issue types without retrieving every single ticket in the project.

**Does this MCP Server support both Cloud and self-hosted Plane instances?**
It does. You simply provide your API credentials—either the standard Plane Cloud key or a custom URL for your own server instance—during setup.

**What is the maximum scope of data returned by `list_projects`?**
The tool handles pagination automatically. If you have hundreds of projects, it fetches them in manageable batches instead of failing due to excessive data volume.

**Can my AI automatically aggregate all open issues inside our active sprint?**
Yes. First, request the active iteration window by calling `list_cycles`. The agent will isolate today's active cycle bounds. Following that, it will invoke `list_work_items` directly constrained by that cycle object, outputting an exhaustive summary of untouched or blocking tickets.

**How does the agent handle custom workspace slugs or self-hosted URLs?**
The system dynamically accepts a `PLANE_BASE_URL` credential. If you are doing an on-premise installation running inside your homelab or company AWS cloud, you merely inject your private domain (e.g., `https://plane.internal.acme.com`). The workspace slug is seamlessly accepted as a contextual execution parameter during standard query prompts.

**Can I request specific details of a long-term module (epic)?**
You can instruct the agent to execute `list_modules`. It extracts the cross-functional epics spanning your workspace project. Your AI can read these top-level module architectures to contextually understand what the core functionality of the project repository aims to achieve.