Developers

Build on WeeklyPlanner

Use the public API for tasks, groups, preferences, profile, and automation flows. The MCP server follows the same API surface with 16 atomic tools.

Create an accountLog in/settings

AI can call the same task model

list_tasks({ date_from, date_to })
update_task({ task_id, date, time_block })
delete_task_series({ series_id })

MCP tools and the public API share the same boundary: recurring templates stay hidden by default while visible task instances remain safe to manage.

WeeklyPlanner week view managed through API and MCP
list_tasksupdate_taskdelete_task_series

REST API

Task, group, profile, settings, stats, subscription, and API key endpoints live under /api/v1.

API Keys & Scopes

Create API keys from account settings and limit them to the scopes your integration actually needs.

MCP Server

16 atomic tools with full data-dictionary descriptions. AI reads the tool descriptions to know exactly which fields each call accepts and returns, then composes the operations itself.

Security

Supabase Auth protects the app. API key verification, scopes, and rate limits share the main API entry path.

Quickstart

1. Create an account

Sign up first, then open Settings to manage your account-level developer access.

2. Create an API key

Generate a key in Settings, choose only the scopes you need, and store it immediately. The plain key is shown once.

3. Call the API or MCP

Send the key as a Bearer token. MCP requests also set X-WeeklyPlanner-Source: mcp.

Examples

Read tasks

curl -X GET "https://weeklyplanner.cc/api/v1/tasks?date_from=2026-03-01&date_to=2026-03-31" \
  -H "Authorization: Bearer wp_your_api_key" \
  -H "Content-Type: application/json"

Create a task

curl -X POST "https://weeklyplanner.cc/api/v1/tasks" \
  -H "Authorization: Bearer wp_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Prepare weekly review",
    "date": "2026-03-20",
    "time_block": "evening",
    "priority": "high"
  }'

MCP Quickstart

Install

npm install -g weeklyplanner-mcp

Claude Code

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

# macOS / Linux
export WEEKLYPLANNER_API_URL="https://weeklyplanner.cc"
export WEEKLYPLANNER_API_KEY="wp_your_api_key"

# Windows PowerShell
$env:WEEKLYPLANNER_API_URL="https://weeklyplanner.cc"
$env:WEEKLYPLANNER_API_KEY="wp_your_api_key"

Claude Desktop

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

After setup, ask your AI: "List my tasks for this week" to verify the connection.

Atomic MCP patterns

Read today's full task context

Call list_tasks with { date: "YYYY-MM-DD" }. The tool returns the full task objects, so AI can inspect time_block, notes, tags, recurrence_rule, defer_count, and overdue_days in one call.

Update one task without a scenario tool

Call update_task with only the fields you want to change, for example { task_id, completed: true } or { task_id, date: "2026-03-29" }.

Compose a wider planning view

Combine get_user_profile, get_settings, get_subscription, get_stats({ date_from, date_to }), and filtered list_tasks calls instead of relying on pre-built 'review' or 'summary' tools.

Available scopes

Grant the smallest scope set possible for each integration.

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

Core endpoints

Tasks

List, create, update, delete, batch update, and reorder task positions.

Groups

Manage group names, colors, ordering, and group-aware task moves.

Settings & Profile

Read and update view preferences, locale, ADHD mode, and personal profile fields.

Stats & Subscription

Read aggregate statistics and subscription status for dashboards or assistant workflows.

Reference docs and copy-paste examples will keep expanding. Billing already runs through Creem inside the product, but public developer endpoints still focus on tasks, settings, stats, subscription, and API keys.