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