MCP task manager

Connect Your AI to a Real Weekly Plan

Run weeklyplanner-mcp as a local MCP server and let compatible AI clients work with the same tasks, groups, settings, and planning data you use in WeeklyPlanner.

Create an accountExplore connection options
19 core tools available by default4 optional Planning V2 tools23 total tools in the manifest

A real plan, not a mock integration

Your assistant works through a scoped connection

Create a revocable key in WeeklyPlanner, connect a compatible agent, and let the workflow read or update the same plan you can inspect in the app.

  1. Your request
  2. Task Planner Skill
  3. Scoped MCP or API
  4. WeeklyPlanner plan
WeeklyPlanner mobile settings showing the connection area
Real settings UIScoped permissionsRevocable key

What an AI client can do

The MCP server exposes focused tools instead of handing an assistant unrestricted application access.

Read and organize tasks

List tasks with date, completion, group, tag, and search filters; inspect one task; then create, update, batch-update, or delete work through explicit tools.

Manage recurring work safely

Read recurring-series context, stop future instances from a chosen date, or delete a whole series through dedicated operations instead of mutating hidden templates.

Use groups, settings, and profile context

Read or update groups, planning preferences, locale, profile fields, and subscription context when the API key includes the required scopes.

Review planning patterns

Read task statistics by default. When Planning V2 is enabled in both the MCP process and backend, add day reviews, planning context, task-pattern aggregates, and atomic heterogeneous patches.

Supported MCP clients

The package uses the standard local stdio transport. These verified setup paths do not require a hosted MCP endpoint.

Claude Desktop

Launch the package from your desktop MCP configuration and pass the API URL and key through the server environment.

Claude Code

Register the same npx command with Claude Code, then provide the two environment variables through your shell or user-level MCP configuration.

Other stdio-compatible clients

Use the same command and environment variables in any MCP client that can launch a local stdio server, including clients such as Cursor.

Install and connect

Create a scoped API key in WeeklyPlanner Settings first. The examples use npx so the client can run the published package without a separate global install.

Create an API key in Settings

Run the package

Use this command to download and start the current published MCP server on stdio.

npx -y weeklyplanner-mcp

Add it to Claude Code

Register the server command, then set WEEKLYPLANNER_API_URL and WEEKLYPLANNER_API_KEY in the environment used to launch Claude Code.

claude mcp add weeklyplanner -- npx -y weeklyplanner-mcp

Configure Claude Desktop

Add this server block to your Claude Desktop MCP configuration. Replace the placeholder with a key created in Settings.

{
  "mcpServers": {
    "weeklyplanner": {
      "command": "npx",
      "args": ["-y", "weeklyplanner-mcp"],
      "env": {
        "WEEKLYPLANNER_API_URL": "https://weeklyplanner.cc",
        "WEEKLYPLANNER_API_KEY": "wp_your_api_key"
      }
    }
  }
}

Verify the connection

Restart the client after changing its MCP configuration, then verify discovery before asking the assistant to make changes.

  1. 1

    Confirm tool discovery

    Open the client's MCP or tools panel and confirm that list_tasks appears. Core installations expose the full default tool set, not only one test tool.

  2. 2

    Run a read-only prompt

    Ask: “List my unfinished tasks for this week.” The client should call list_tasks and return structured task data without changing the plan.

  3. 3

    Check the boundary

    If the key lacks a required scope, the API should reject the call. Add only the missing scope instead of replacing the key with broad access.

MCP tools by category

Names and counts below come directly from the repository manifest, keeping this page aligned with the implemented server.

Tasks and recurring series

Read, create, update, delete, reorder, and batch-change tasks, with dedicated operations for recurring series.

9 Core
list_tasksget_taskcreate_taskupdate_taskdelete_taskdelete_task_seriesget_seriesstop_task_series_frombatch_update_tasks

Groups

List and maintain the groups that organize tasks across the planner.

4 Core
list_groupscreate_groupupdate_groupdelete_group

Profile, settings, and subscription

Read or update personal planning context and preferences, and read the current subscription.

5 Core
get_user_profileupdate_user_profileget_settingsupdate_settingsget_subscription

Statistics and planning analysis

Read current statistics, plus optional Planning V2 reviews, context, patterns, and atomic patches.

1 Core4 Planning V2
get_statsbatch_patch_tasksget_day_reviewget_planning_contextget_task_patterns

Planning V2 tools are optional. They appear only when PLANNING_V2_BACKEND_ENABLED=true is set for the MCP process and the connected backend has the same capability enabled.

Use the smallest API scopes

API keys can be limited to read or write access for tasks, groups, statistics, settings, and profile data. Create a separate key for each AI client so it can be revoked without disrupting other integrations.

tasks:readtasks:writegroups:readgroups:writestats:readsettings:readsettings:writeprofile:readprofile:write

Security boundaries

Keep the key in the client environment

Do not paste an API key into prompts, source files, screenshots, or shared configuration. The MCP process reads it from WEEKLYPLANNER_API_KEY.

Separate read and write access

Use a read-only key for summaries and reviews. Add write scopes only when the client must create, move, edit, or delete data.

Treat client approval as a separate control

The server enforces authentication, scopes, validation, and rate limits. Approval prompts for external MCP calls depend on the AI client, so review its tool-permission settings before enabling writes.

Revoke keys you no longer use

Create one key per connection and revoke it from Settings when a device, client, or workflow is retired.

Troubleshooting

The MCP server does not appear

Confirm Node.js and npx are available to the client process, validate the JSON configuration, and fully restart the client after saving changes.

Calls return Unauthorized

Generate an active API key in Settings, remove accidental quotes or line breaks, and confirm WEEKLYPLANNER_API_URL points to the same WeeklyPlanner deployment where the key was created.

A call is forbidden

The key is valid but lacks the required scope. Add only the relevant read or write scope, or generate a replacement key with the correct minimum permissions.

Planning analysis tools are missing

This is expected when Planning V2 is disabled. The core tools remain available; enable the optional flag only when the connected backend supports those endpoints.

Requests are rate-limited

Wait for the current quota window to reset or reduce repeated calls. Avoid retry loops that issue the same planning request continuously.

Explore related pages

ConnectMCP Task Manager GuideAI Weekly PlannerTime Blocking PlannerPlans and API Limits

MCP task manager FAQ

What is an MCP task manager?
An MCP task manager exposes structured task operations to compatible AI clients through the Model Context Protocol. The AI calls explicit tools instead of relying on pasted task lists or direct database access.
Does the MCP server use my real WeeklyPlanner tasks?
Yes. It calls the same scoped public API used for account-level integrations, so changes appear in the planner rather than in a separate copy.
Do I need a paid plan to try it?
No. A free account can create an API key and use the included API/MCP request allowance. Paid plans increase the available quota.
Are all MCP tools always enabled?
The core tools are available by default. Planning V2 adds a separate optional set for day reviews, planning context, task patterns, and heterogeneous task patches.