planflow-mcp

MCP (Model Context Protocol) server for PlanFlow - AI-native project management from your terminal.

Overview

This package provides a MCP server that integrates PlanFlow with Claude Code, allowing you to manage projects and tasks directly from your AI-powered development workflow.

Quick Start

# 1. Install globally
npm install -g planflow-mcp

# 2. Add to Claude Desktop config (~/.config/claude/claude_desktop_config.json)
{
  "mcpServers": {
    "planflow": {
      "command": "planflow-mcp"
    }
  }
}

# 3. Restart Claude Desktop

# 4. In Claude, login with your API token
"Login to PlanFlow with token pf_xxxxx"

Requires Node.js >= 20.0.0. See INSTALLATION.md for detailed setup instructions.

Installation

npm install -g planflow-mcp

Or with pnpm:

pnpm add -g planflow-mcp

Need help? See the complete installation guide for detailed instructions, troubleshooting, and configuration options.

Configuration

Option 1: CLI Command (Recommended)

claude mcp add --transport stdio --scope user planflow-mcp -- planflow-mcp

This automatically adds PlanFlow to your Claude Code configuration.

Option 2: Manual Configuration

Add the MCP server to your Claude Code configuration file (~/.claude.json or ~/.config/claude/settings.json):

{
  "mcpServers": {
    "planflow": {
      "command": "planflow-mcp"
    }
  }
}

Or if installed locally in a project:

{
  "mcpServers": {
    "planflow": {
      "command": "npx",
      "args": ["planflow-mcp"]
    }
  }
}

After configuration, restart Claude Code to load the MCP server.

Authentication

Before using PlanFlow tools, authenticate with your API token:

1. Get your API token from planflow.tools/settings/api
2. Use the planflow_login tool in Claude Code with your token

Available Tools

Auth

| Tool | Description | |------|-------------| | planflow_login | Authenticate with your PlanFlow API token | | planflow_logout | Clear stored credentials | | planflow_whoami | Show current authenticated user |

Projects & Tasks

| Tool | Description | |------|-------------| | planflow_projects | List all your projects | | planflow_create | Create a new project | | planflow_use | Set the current project (used by other tools when projectId is omitted) | | planflow_sync | Sync local PROJECT_PLAN.md to cloud (push/pull) | | planflow_task_list | List tasks for a project | | planflow_task_update | Update task status | | planflow_task_next | Get the next recommended task | | planflow_working_on | Signal which task you are actively working on |

Activity & Collaboration

| Tool | Description | |------|-------------| | planflow_activity | View recent activity (project or task scope) | | planflow_changes | View recent changes (lighter-weight stream) | | planflow_comments | View comments on a task | | planflow_comment | Add a comment / @-mention on a task | | planflow_notifications | View and manage your notifications |

Intelligence Layer (RAG)

| Tool | Description | |------|-------------| | planflow_index | Index code/docs into the project vector DB. Two modes: directory (recursive scan) or files (explicit list) | | planflow_index_status | Report index size, file/language breakdown, and staleness | | planflow_search | Hybrid semantic + keyword search (Voyage-code-3 + BM25) over indexed content | | planflow_context | Combined context: knowledge + vector + real-time + activity layers | | planflow_recall | Aggregate everything PlanFlow knows about a single anchor — file, task, or chunk | | planflow_remember | Save a knowledge entry (architecture decision, pattern, convention, etc.) |

Usage Examples

Login

Use planflow_login with my API token: pf_xxxxx

List Projects

Show me my PlanFlow projects

Sync Project Plan

Sync my PROJECT_PLAN.md to PlanFlow

Update Task Status

Mark task T1.5 as done in PlanFlow

Get Next Task

What should I work on next?

Environment Variables

| Variable | Description | Default | |----------|-------------|---------| | PLANFLOW_API_URL | API server URL | https://api.planflow.tools | | PLANFLOW_DEBUG | Enable debug logging | false |

Configuration Storage

Credentials are stored in ~/.config/planflow/config.json:

{
  "apiUrl": "https://api.planflow.tools",
  "token": "pf_...",
  "userId": "...",
  "email": "..."
}

Requirements

• Node.js >= 20.0.0
• Claude Code with MCP support

Development

# Install dependencies
pnpm install

# Run in development mode
pnpm dev

# Build for production
pnpm build

# Run tests
pnpm test

# Run tests with coverage
pnpm test:coverage

License

MIT - see LICENSE for details.

Links

• Installation Guide - Detailed setup instructions
• Full MCP Documentation - Comprehensive docs site guide
• Getting Started - Complete onboarding guide
• PlanFlow Website
• Documentation
• GitHub Repository
• Report Issues