Skip to content

feat: Add comprehensive Pages API support with session authentication #43

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
koke1997 wants to merge 10 commits into
base: canary
Choose a base branch
from
+1,695 −22
Open

feat: Add comprehensive Pages API support with session authentication #43

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
10 commits
Select commit Hold shift + click to select a range
d86df96
feat: Add comprehensive Pages API support with session authentication
koke1997 Nov 15, 2025
0c5fdf5
fix: Validate session cookies are received before marking auth as suc…
koke1997 Nov 15, 2025
7a31baf
fix: Address CodeRabbit review feedback for Pages API implementation
koke1997 Nov 15, 2025
1b22916
fix: Address security and cross-platform robustness issues
koke1997 Nov 15, 2025
28615e9
fix: Address remaining code review feedback - session verification an…
koke1997 Nov 15, 2025
4608a5a
fix: CRITICAL - Remove session cookie plaintext logging
koke1997 Nov 15, 2025
974fae4
fix(auth): relax cookie validation and support multiple cookie names
koke1997 Dec 12, 2025
01cfbe2
refactor: secure logging and centralized debug module
koke1997 Dec 12, 2025
4eaa546
feat: Add Origin header for cloud authentication and update Pages API…
koke1997 Jan 24, 2026
cc5a97e
docs: Add comprehensive setup guide for Pages API
koke1997 Jan 24, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
153 changes: 152 additions & 1 deletion README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -324,21 +324,126 @@ This server unlocks all sorts of useful capabilities for anyone working with Pla
- Parameters:
- `project_id` (string, required): UUID of the project
- `issue_id` (string, required): UUID of the issue
- `worklog_id` (string, required): UUID of the worklog
- `worklog_id` (string, required): UUID of the worklog

### Pages (Session Authentication Required)

**Note:** Pages API tools require session authentication. Use `plane_login` first with your email and password.

- `plane_login`
- Authenticate with Plane using email and password
- Parameters:
- `email` (string, required): Your Plane account email
- `password` (string, required): Your Plane account password
- `api_host_url` (string, optional): Plane API URL (defaults to https://api.plane.so/)

- `list_pages`
- List all pages in a project
- Parameters:
- `project_id` (string, required): UUID of the project

- `get_page`
- Get details of a specific page
- Parameters:
- `project_id` (string, required): UUID of the project
- `page_id` (string, required): UUID of the page

- `create_page`
- Create a new page
- Parameters:
- `project_id` (string, required): UUID of the project
- `name` (string, required): Page name
- `description` (string, optional): Page description
- `access` (integer, optional): Access level (0=public, 1=private)

- `update_page`
- Update a page's properties
- Parameters:
- `project_id` (string, required): UUID of the project
- `page_id` (string, required): UUID of the page
- `name` (string, optional): New page name
- `description` (string, optional): New description
- `access` (integer, optional): New access level

- `delete_page`
- Delete a page permanently
- Parameters:
- `project_id` (string, required): UUID of the project
- `page_id` (string, required): UUID of the page

- `lock_page` / `unlock_page`
- Lock or unlock a page for editing
- Parameters:
- `project_id` (string, required): UUID of the project
- `page_id` (string, required): UUID of the page

- `favorite_page` / `unfavorite_page`
- Add or remove page from favorites
- Parameters:
- `project_id` (string, required): UUID of the project
- `page_id` (string, required): UUID of the page

- `archive_page` / `unarchive_page`
- Archive or restore a page
- Parameters:
- `project_id` (string, required): UUID of the project
- `page_id` (string, required): UUID of the page

- `duplicate_page`
- Create a copy of a page
- Parameters:
- `project_id` (string, required): UUID of the project
- `page_id` (string, required): UUID of the page to duplicate

- `get_page_description` / `update_page_description`
- Get or update page HTML content
- Parameters:
- `project_id` (string, required): UUID of the project
- `page_id` (string, required): UUID of the page
- `description_html` (string, required for update): HTML content

- `get_page_versions` / `get_page_version`
- Get page version history
- Parameters:
- `project_id` (string, required): UUID of the project
- `page_id` (string, required): UUID of the page
- `version_id` (string, required for specific version): UUID of the version

- `get_pages_summary`
- Get pages statistics for a project
- Parameters:
- `project_id` (string, required): UUID of the project


## Configuration Parameters

### For API Key Authentication (Most Tools)
- `PLANE_API_KEY` - Your Plane API token. You can generate one from the Workspace Settings > API Tokens page (`/settings/api-tokens/`) in the Plane app.
- `PLANE_WORKSPACE_SLUG` - The workspace slug for your Plane instance. The workspace-slug represents the unique workspace identifier for a workspace in Plane. It can be found in the URL.
- `PLANE_API_HOST_URL` (optional) - The host URL of the Plane API Server. Defaults to https://api.plane.so/

### For Session Authentication (Pages API Only)
Pages API tools require session authentication using email/password instead of API key. Use the `plane_login` tool before accessing Pages tools.

**Environment variables for Pages authentication:**
- `PLANE_EMAIL` (optional) - Your Plane account email for session authentication
- `PLANE_PASSWORD` (optional) - Your Plane account password for session authentication

**Note:** You can either:
1. Set these environment variables in your MCP client configuration, OR
2. Call `plane_login` tool manually with email/password when needed

**Authentication methods by feature:**
- **Projects, Issues, Modules, Cycles, Labels, States, Work Logs**: API Key (PLANE_API_KEY)
- **Pages**: Session Auth (email/password via `plane_login` tool)

Comment on lines +425 to +439
Copy link

@coderabbitai coderabbitai bot Jan 24, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

⚠️ Potential issue | 🟠 Major

Security concern: Plaintext password storage in environment variables.

Storing passwords in environment variables or configuration files creates several security risks:

  • Credentials may be accidentally committed to version control
  • Passwords visible in process listings (ps, top)
  • Potential exposure through logs, error messages, or system dumps
  • Accessible to other processes running under the same user

The documentation should warn users about these risks and recommend:

  1. Preferring the manual plane_login approach (Option 2) over environment variables when possible
  2. Using secret management tools (e.g., encrypted vaults, OS keychains) if environment variables are necessary
  3. Avoiding committing credentials to version control (add to .gitignore)
  4. Restricting file permissions on configuration files containing credentials
📋 Suggested documentation enhancement

Add a security warning after line 434:

**Security Warning:** Storing passwords in plaintext configuration files or environment variables poses security risks. Consider:
- Using the `plane_login` tool interactively rather than storing credentials in env vars
- If env vars are necessary, use a secrets manager or encrypted credential store
- Never commit configuration files containing passwords to version control
- Restrict file permissions (e.g., `chmod 600`) on files containing credentials
🤖 Prompt for AI Agents 
In `@README.md` around lines 425 - 439, Add a security warning to the Pages
authentication section explaining risks of storing plaintext passwords in
environment variables (PLANE_EMAIL, PLANE_PASSWORD) and recommend preferring
manual plane_login usage, using a secrets manager or OS keychain if env vars are
required, preventing credentials from being committed to version control (e.g.,
.gitignore), and restricting file permissions on any credential files; insert
this warning near the Pages auth block so readers of the README see it alongside
the plane_login instructions and the distinction between PLANE_API_KEY (API key)
and session auth.

## Usage

### Claude Desktop

You can add Plane to [Claude Desktop](https://modelcontextprotocol.io/quickstart/user) by updating your `claude_desktop_config.json`:

**For standard API key authentication (Projects, Issues, etc.):**
```json
{
"mcpServers": {
Expand All @@ -358,10 +463,35 @@ You can add Plane to [Claude Desktop](https://modelcontextprotocol.io/quickstart
}
```

**To also use Pages API (with session authentication):**
```json
{
"mcpServers": {
"plane": {
"command": "npx",
"args": [
"-y",
"@makeplane/plane-mcp-server"
],
"env": {
"PLANE_API_KEY": "<YOUR_API_KEY>",
"PLANE_API_HOST_URL": "<HOST_URL_FOR_SELF_HOSTED>",
"PLANE_WORKSPACE_SLUG": "<YOUR_WORKSPACE_SLUG>",
"PLANE_EMAIL": "<YOUR_EMAIL>",
"PLANE_PASSWORD": "<YOUR_PASSWORD>"
}
}
}
}
```

**Note:** If you don't set `PLANE_EMAIL` and `PLANE_PASSWORD`, you can still use Pages tools by calling `plane_login` manually in your conversation.

### VSCode

You can also connect Plane to [VSCode](https://code.visualstudio.com/docs/copilot/chat/mcp-servers#_add-an-mcp-server) by editing your `.vscode.json` or `mcp.json` file:

**For standard API key authentication:**
```json
{
"servers": {
Expand All @@ -379,7 +509,28 @@ You can also connect Plane to [VSCode](https://code.visualstudio.com/docs/copilo
}
}
}
```

**To also use Pages API (with session authentication):**
```json
{
"servers": {
"plane": {
"command": "npx",
"args": [
"-y",
"@makeplane/plane-mcp-server"
],
"env": {
"PLANE_API_KEY": "<YOUR_API_KEY>",
"PLANE_API_HOST_URL": "<HOST_URL_FOR_SELF_HOSTED>",
"PLANE_WORKSPACE_SLUG": "<YOUR_WORKSPACE_SLUG>",
"PLANE_EMAIL": "<YOUR_EMAIL>",
"PLANE_PASSWORD": "<YOUR_PASSWORD>"
}
}
}
}
```

## License
Expand Down
133 changes: 133 additions & 0 deletions SETUP_GUIDE.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,133 @@
# Plane MCP Server - Pages API Setup Guide

## Quick Start

### 1. Install
```bash
npm install -g @makeplane/plane-mcp-server
```

### 2. Configure Your MCP Client

#### For Claude Desktop

Edit `~/Library/Application Support/Claude/claude_desktop_config.json`:

```json
{
"mcpServers": {
"plane": {
"command": "npx",
"args": ["-y", "@makeplane/plane-mcp-server"],
"env": {
"PLANE_API_KEY": "your-api-key-here",
"PLANE_WORKSPACE_SLUG": "your-workspace-slug",
"PLANE_API_HOST_URL": "https://api.plane.so/",
"PLANE_EMAIL": "your-email@example.com",
"PLANE_PASSWORD": "your-password"
}
}
}
}
```

#### For VSCode

Edit `~/.vscode/mcp.json`:

```json
{
"servers": {
"plane": {
"command": "npx",
"args": ["-y", "@makeplane/plane-mcp-server"],
"env": {
"PLANE_API_KEY": "your-api-key-here",
"PLANE_WORKSPACE_SLUG": "your-workspace-slug",
"PLANE_API_HOST_URL": "https://api.plane.so/",
"PLANE_EMAIL": "your-email@example.com",
"PLANE_PASSWORD": "your-password"
}
}
}
}
```

### 3. Environment Variables

#### Required for All Features
- `PLANE_API_KEY` - Get from Workspace Settings > API Tokens in Plane
- `PLANE_WORKSPACE_SLUG` - Found in your Plane workspace URL

#### Optional
- `PLANE_API_HOST_URL` - Defaults to `https://api.plane.so/` (set for self-hosted)

#### For Pages API Only
- `PLANE_EMAIL` - Your Plane account email
- `PLANE_PASSWORD` - Your Plane account password

**Note:** If you don't set email/password, you can still use Pages tools by calling `plane_login` manually in your conversation.

## Authentication Methods

### API Key Authentication
Used for most tools:
- Projects, Issues, Modules, Cycles
- Labels, States, Issue Types
- Work Logs

### Session Authentication
Required for Pages API tools:
- All 18 Pages API tools
- Use `plane_login` tool or set `PLANE_EMAIL`/`PLANE_PASSWORD` env vars

## Testing Your Setup

### Test API Key Authentication
Ask your AI assistant:
```
"List my Plane projects"
```

### Test Pages Authentication
Ask your AI assistant:
```
"Login to Plane with my credentials and list pages in project <project-id>"
```
Comment on lines +88 to +96
Copy link

@coderabbitai coderabbitai bot Jan 24, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

⚠️ Potential issue | 🟡 Minor

Add language identifiers to fenced blocks.

This resolves MD040 and improves readability.

📝 Suggested update 
-```
+```text
 "List my Plane projects"

@@
- +text
"Login to Plane with my credentials and list pages in project "

</details>

<!-- suggestion_start -->

<details>
<summary>📝 Committable suggestion</summary>

> ‼️ **IMPORTANT**
> Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.

```suggestion
🧰 Tools
🪛 markdownlint-cli2 (0.18.1)

88-88: Fenced code blocks should have a language specified

(MD040, fenced-code-language)

94-94: Fenced code blocks should have a language specified

(MD040, fenced-code-language)

🤖 Prompt for AI Agents 
In `@SETUP_GUIDE.md` around lines 88 - 96, Fenced code blocks containing the
example prompts "List my Plane projects" and "Login to Plane with my credentials
and list pages in project <project-id>" lack language identifiers; update those
triple-backtick blocks to include a language tag (e.g., text) so the blocks
become ```text ... ``` to satisfy MD040 and improve readability, ensuring both
instances in the document are changed.


## Troubleshooting

### Pages API Not Working
1. Verify you've called `plane_login` or set `PLANE_EMAIL`/`PLANE_PASSWORD`
2. Check your password is correct (no SSO - must be email/password account)
3. For cloud instances, ensure you're using `https://api.plane.so/`

### API Key Authentication Failing
1. Verify your API key is valid in Plane settings
2. Check `PLANE_WORKSPACE_SLUG` matches your workspace URL
3. For self-hosted, verify `PLANE_API_HOST_URL` is correct

## Self-Hosted Plane

Set `PLANE_API_HOST_URL` to your instance:
```json
{
"env": {
"PLANE_API_HOST_URL": "http://your-plane-instance.com/",
...
}
}
```

## Security Notes

- Store credentials securely in your MCP client config
- Don't share your API keys or passwords
- Use environment-specific credentials (dev vs prod)
- Consider using separate API keys for different tools

## Getting Help

- [Plane Documentation](https://docs.plane.so)
- [MCP Documentation](https://modelcontextprotocol.io)
- [GitHub Issues](https://github.com/makeplane/plane-mcp-server/issues)
Loading