JJ Planner MCP Server

An MCP (Model Context Protocol) server that connects AI agents (Cursor, Claude, etc.) to JJ Planner — a project management PWA. Agents can query, create, update, and delete projects, tasks, and schedules through this server.

Requirements

• Node.js 22.x or higher
• A valid JJ Planner API key (issued from JJ Planner settings page)

Installation

Via npm (recommended):

npm install -g @vncy/jj-planner-mcp

From source:

git clone https://github.com/Vince-Yi/-vncy-jj-planner-mcp.git
cd -vncy-jj-planner-mcp
npm install
npm run build

Configuration

Copy .env.example to .env and fill in your credentials:

cp .env.example .env

JJ_PLANNER_API_BASE_URL=https://your-backend-url.com
JJ_PLANNER_API_KEY=jjp_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

Variable	Description
JJ_PLANNER_API_BASE_URL	Base URL of the JJ Planner backend
JJ_PLANNER_API_KEY	API key in the format jjp_ + 64-char hex (68 chars total)

Registering with Cursor

Add the following to your Cursor mcp.json:

{
    "mcpServers": {
        "jj-planner": {
            "command": "npx",
            "args": ["-y", "@vncy/jj-planner-mcp"],
            "env": {
                "JJ_PLANNER_API_BASE_URL": "https://your-backend-url.com",
                "JJ_PLANNER_API_KEY": "jjp_..."
            }
        }
    }
}

Registering with Claude Code

Add to your claude_desktop_config.json (or Claude Code MCP settings):

{
    "mcpServers": {
        "jj-planner": {
            "command": "npx",
            "args": ["-y", "@vncy/jj-planner-mcp"],
            "env": {
                "JJ_PLANNER_API_BASE_URL": "https://your-backend-url.com",
                "JJ_PLANNER_API_KEY": "jjp_..."
            }
        }
    }
}

Available Tools

Projects

Tool	Required Args	Optional Args	Description
list_projects	—	—	List all projects
get_project	projectId	—	Get project details

Groups

Tool	Required Args	Optional Args	Description
list_groups	projectId	—	List groups in a project

Tasks

Tool	Required Args	Optional Args	Description
list_tasks	projectId	—	List tasks in a project
get_task	taskId	—	Get task details
create_task	projectId, title	groupId, assignees, status, progress	Create a new task
update_task	taskId	title, groupId, assignees, status, progress	Update a task
delete_task	taskId	—	Delete a task

Task status values: pending / in_progress / completed

Task progress: integer from 0 to 100

Schedules

Tool	Required Args	Optional Args	Description
list_schedules	projectId	taskId	List schedules (all or per task)
create_schedule	taskId, projectId, startDate, startHalf, endDate, endHalf	title	Create a new schedule
update_schedule	scheduleId	startDate, startHalf, endDate, endHalf, title	Update a schedule
delete_schedule	scheduleId	—	Delete a schedule

Date format: YYYY-MM-DD

Half-day values: AM / PM

Project Structure

jj-planner-mcp/
├── package.json
├── tsconfig.json
├── .env.example
└── src/
    ├── index.ts          # MCP server entry point, tool registration, stdio transport
    ├── client.ts         # axios instance with X-API-Key header and response unwrapping
    └── tools/
        ├── projects.ts   # list_projects, get_project
        ├── groups.ts     # list_groups
        ├── tasks.ts      # list_tasks, get_task, create_task, update_task, delete_task
        └── schedules.ts  # list_schedules, create_schedule, update_schedule, delete_schedule

Scripts

Command	Description
npm run build	Compile TypeScript to dist/
npm start	Run the compiled server
npm run dev	Run directly with ts-node (development)

Authentication

Every request to the JJ Planner backend includes the following header:

X-API-Key: <your-api-key>

The API key can be generated from the JJ Planner settings page. It follows the format jjp_ followed by 64 hexadecimal characters (68 characters total).

License

MIT