plane-mcp-server: Instructions file for Claude Code

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

Project Overview

Plane MCP Server — a Python-based Model Context Protocol server that exposes Plane's project management API as MCP tools. Built on FastMCP with the official plane-sdk. Supports three transport modes: stdio (local), HTTP (with OAuth or header auth), and SSE (legacy).

Common Commands

# Install dependencies (uses uv)
uv pip install -e ".[dev]"

# Run the server locally (stdio mode)
PLANE_API_KEY=... PLANE_WORKSPACE_SLUG=... python -m plane_mcp stdio

# Run HTTP server
python -m plane_mcp http

# Run all tests
pytest

# Run a single test
pytest tests/test_integration.py::test_full_integration -v

# Run tests with env vars from file
export $(cat .env.test.local | xargs) && pytest tests/ -v

# Format code (line length: 120)
ruff format plane_mcp/

# Lint (rules: E, F, I, UP, B; line length: 120)
ruff check plane_mcp/

Architecture

Entry Point & Transport Modes

plane_mcp/__main__.py parses a positional arg (stdio, http, or sse) and launches the corresponding server:

• stdio: Requires PLANE_API_KEY + PLANE_WORKSPACE_SLUG env vars. Runs locally.
• http: Starts on port 8211 with two auth endpoints — OAuth (/oauth/mcp) and header-based PAT (/http/api-key/mcp).
• sse: Legacy OAuth-only SSE transport.

Server Factories (server.py)

Three factory functions (get_oauth_mcp, get_header_mcp, get_stdio_mcp) each create a FastMCP instance, register all tools, and configure the appropriate auth provider. OAuth/HTTP modes use Redis for token storage (falls back to in-memory).

Client Context (client.py)

get_plane_client_context() returns a PlaneClientContext(client, workspace_slug) namedtuple. It resolves credentials from the MCP request context (OAuth token or header API key) or from environment variables (stdio mode). Prefers PLANE_INTERNAL_BASE_URL for server-to-server calls.