reclaim-mcp-server
This server provides AI assistants with programmatic access to manage Reclaim.ai calendars, tasks, habits, focus time, and analytics through 40+ tools.
Task Management: Create tasks with auto-scheduling, priorities (P1-P4), duration, due dates, and chunk sizes. Track progress with start/stop timers, time logs, and status updates (NEW, SCHEDULED, IN_PROGRESS, COMPLETE, ARCHIVED). List, update, complete, delete, prioritize, and restart tasks.
Calendar & Events: View calendar events and Reclaim-managed personal events (tasks, habits, focus time) within date ranges with filtering options. Get detailed information for specific events.
Smart Habits: Create recurring habits with customizable frequency (daily, weekly, monthly, yearly), ideal times, durations, and defense levels. Manage instances by marking done, skipping, enabling, or disabling habits.
Focus Time Management: View and update focus settings including duration ranges (min/ideal/max) and defense aggression levels. Control individual focus blocks by locking, unlocking, or rescheduling them. Access focus analytics with protected hours, interruptions, and recommendations.
Analytics & Insights: Track productivity metrics with time breakdowns by category and date. Analyze focus time patterns and monitor time allocation across event categories.
System Operations: Verify API connectivity, check server health, and use flexible tool profiles (minimal/standard/full) to customize exposed functionality for different use cases.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@reclaim-mcp-server create a 1-hour task to review project proposal, due tomorrow"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
Reclaim.ai MCP Server (UNOFFICIAL)
UNOFFICIAL – Not affiliated with Reclaim.ai. Uses their public API , use at your own risk.
Control your Reclaim.ai calendar, tasks, and habits from AI assistants via MCP.
What You Can Do
"Create a 2-hour task to review the Q1 budget, due Friday"
"What's on my calendar tomorrow?"
"Mark my morning workout habit as done"
"Show me my productivity stats for last week"
"Start a focus block for the next 90 minutes"40 tools across tasks, calendar, habits, focus time, and analytics. See docs/TOOLS.md for complete reference.
Related MCP server: PostIdentity MCP Server
Quick Start
1. Get your API key: https://app.reclaim.ai/settings/developer
2. Install
pip install reclaim-mcp-server3. Configure Claude Desktop (~/Library/Application Support/Claude/claude_desktop_config.json)
{
"mcpServers": {
"reclaim": {
"command": "uvx",
"args": ["reclaim-mcp-server"],
"env": { "RECLAIM_API_KEY": "your_key_here" }
}
}
}4. Restart Claude Desktop
Installation Options
Method | Command |
uvx (recommended) |
|
pip |
|
Smithery |
|
Docker |
|
Source |
|
Registries: PyPI · Smithery · Glama · GitHub · GitLab
Tool Profiles
Limit exposed tools via RECLAIM_TOOL_PROFILE:
Profile | Tools | Use Case |
| 20 | Basic task/habit management |
| 32 | Daily productivity |
| 40 | All features (default) |
{
"mcpServers": {
"reclaim": {
"command": "uvx",
"args": ["reclaim-mcp-server"],
"env": {
"RECLAIM_API_KEY": "your_key_here",
"RECLAIM_TOOL_PROFILE": "standard"
}
}
}
}Other Configurations
{
"mcpServers": {
"reclaim": {
"command": "docker",
"args": ["run", "-i", "--rm", "-e", "RECLAIM_API_KEY", "universalamateur/reclaim-mcp-server"],
"env": { "RECLAIM_API_KEY": "your_key_here" }
}
}
}{
"mcpServers": {
"reclaim": {
"command": "/opt/homebrew/bin/poetry",
"args": ["--directory", "/path/to/reclaim-mcp-server", "run", "reclaim-mcp-server"],
"env": { "RECLAIM_API_KEY": "your_key_here" }
}
}
}Note: Use --directory flag instead of cwd – Claude Desktop doesn't respect cwd.
Works with any MCP-compatible client. Generic stdio config:
{
"command": "uvx",
"args": ["reclaim-mcp-server"],
"env": { "RECLAIM_API_KEY": "your_key_here" }
}Troubleshooting
Issue | Solution |
"Invalid API key" | Verify key at https://app.reclaim.ai/settings/developer |
Rate limited (429) | Server handles retries automatically; reduce request frequency |
Tools not showing | Restart Claude Desktop after config change |
Docker ARM64 warning | Use v0.8.1+ for native Apple Silicon support |
Development
poetry install
poetry run pytest # Run tests
poetry run black src tests # Format
poetry run mypy src # Type check
poetry run fastmcp dev src/reclaim_mcp/server.py # Dev modeLinks
License
MIT – Falko Sieverding (@UniversalAmateur)
Built with FastMCP · Not affiliated with Reclaim.ai
Available Tools
32 toolsadd_time_to_taskB
Log time spent on a task using Reclaim's planner API.
Args: task_id: The task ID minutes: Minutes worked on the task notes: Optional notes about the work done
Returns: Planner action result confirming time was logged
Inputs: task_id (required), minutes (required), notes. Returns: object
create_habitA
Create a new smart habit for auto-scheduling.
Args: title: Habit name/title ideal_time: Preferred time in "HH:MM" format (e.g., "09:00") duration_min_mins: Minimum duration in minutes frequency: Recurrence (DAILY, WEEKLY, MONTHLY, YEARLY) - default WEEKLY ideal_days: Days for WEEKLY frequency (MONDAY, TUESDAY, etc.) event_type: Type (FOCUS, SOLO_WORK, PERSONAL, etc.) - default SOLO_WORK defense_aggression: Protection level (DEFAULT, NONE, LOW, MEDIUM, HIGH, MAX) duration_max_mins: Maximum duration in minutes (defaults to min duration) description: Optional habit description enabled: Whether habit is active (default True) time_policy_type: Time policy (WORK, PERSONAL, MEETING). Auto-inferred if not provided.
Returns: Created habit object.
Inputs: title (required), ideal_time (required), duration_min_mins (required), frequency, +7 more. Returns: object
create_taskA
Create a new task in Reclaim.ai for auto-scheduling.
Args: title: Task title/description duration_minutes: Total time needed for the task in minutes due_date: ISO date string (YYYY-MM-DD) or None for no deadline min_chunk_size_minutes: Minimum time block size (default 15) max_chunk_size_minutes: Maximum time block size (None = duration) snooze_until: Don't schedule before this datetime (ISO format) priority: P1 (Critical), P2 (High), P3 (Medium), P4 (Low)
Returns: Created task object
Inputs: title (required), duration_minutes (required), due_date, min_chunk_size_minutes, +3 more. Returns: object
delete_habitC
Delete a smart habit.
Args: lineage_id: The habit lineage ID to delete
Returns: True if deleted successfully.
Inputs: lineage_id (required). Returns: result
delete_taskC
Delete a task from Reclaim.ai.
Args: task_id: The task ID to delete
Returns: True if deleted successfully
Inputs: task_id (required). Returns: result
disable_habitA
Disable a habit to pause scheduling without deleting it.
Args: lineage_id: The habit lineage ID to disable
Returns: True if disabled successfully.
Inputs: lineage_id (required). Returns: result
enable_habitB
Enable a disabled habit to resume scheduling.
Args: lineage_id: The habit lineage ID to enable
Returns: Empty dict on success.
Inputs: lineage_id (required). Returns: object
get_eventA
Get a single event by calendar ID and event ID.
Note: Works best with events from list_events (external calendar events). Reclaim-managed events from list_personal_events may return 404.
Args: calendar_id: The calendar ID containing the event event_id: The event ID to retrieve thin: If True, return minimal event data (default False for full details)
Returns: Event object with full details.
Inputs: calendar_id (required), event_id (required), thin. Returns: object
get_focus_insightsB
Get focus time insights and recommendations.
Args: start: Start date in ISO format (e.g., '2026-01-01') end: End date in ISO format (e.g., '2026-01-31')
Returns: Focus time analytics including protected hours, interruptions, etc.
Inputs: start (required), end (required). Returns: object
get_focus_settingsB
Get current focus time settings for the user.
Returns: List of focus settings objects (one per focus type).
Inputs: no named parameters. Returns: result
get_taskB
Get a single task by ID.
Args: task_id: The task ID to retrieve
Returns: Task object with all details.
Inputs: task_id (required). Returns: object
get_user_analyticsB
Get personal productivity analytics for the current user.
Args: start: Start date in ISO format (e.g., '2026-01-01') end: End date in ISO format (e.g., '2026-01-31') metric_name: The metric to retrieve. One of: - DURATION_BY_CATEGORY - DURATION_BY_DATE_BY_CATEGORY
Returns: Analytics data with time breakdowns by category.
Inputs: start (required), end (required), metric_name (required). Returns: object
health_checkB
Check if the server is running.
Inputs: no named parameters. Returns: result
list_completed_tasksB
List completed and archived tasks from Reclaim.ai.
Args: limit: Maximum number of tasks to return (default 50)
Returns: List of completed/archived task objects.
Inputs: limit. Returns: result
list_eventsA
List calendar events within a time range.
Args: start: Start date (e.g., '2026-01-02' or '2026-01-02T00:00:00Z' - time is ignored) end: End date (e.g., '2026-01-02' or '2026-01-02T23:59:59Z' - time is ignored) calendar_ids: Optional list of calendar IDs to filter by event_type: Optional event type filter (EXTERNAL, RECLAIM_MANAGED, etc.) thin: If True, return minimal event data (default True)
Returns: List of event objects with eventId, title, eventStart, eventEnd, etc.
Inputs: start (required), end (required), calendar_ids, event_type, +1 more. Returns: result
list_habitsB
List all smart habits from Reclaim.ai.
Returns: List of habit objects with lineageId, title, enabled, recurrence, etc.
Inputs: no named parameters. Returns: result
list_personal_eventsC
List Reclaim-managed personal events (tasks, habits, focus time).
Args: start: Optional start datetime in ISO format end: Optional end datetime in ISO format limit: Maximum number of events to return (default 50)
Returns: List of personal event objects.
Inputs: start, end, limit. Returns: result
list_tasksA
List active tasks from Reclaim.ai (excludes completed by default).
Args: status: Comma-separated task statuses (NEW, SCHEDULED, IN_PROGRESS, COMPLETE, ARCHIVED) limit: Maximum number of tasks to return (default 50)
Returns: List of task objects with id, title, duration, due_date, status, etc.
Inputs: status, limit. Returns: result
lock_focus_blockA
Lock a focus time block to prevent it from being rescheduled.
Args: calendar_id: The calendar ID containing the focus block event_id: The focus block event ID to lock
Returns: Planner action result with updated event state.
Inputs: calendar_id (required), event_id (required). Returns: object
mark_habit_doneA
Mark a habit instance as done.
Use this to mark today's scheduled habit event as completed.
Args: event_id: The event ID of the specific habit instance (from list_personal_events)
Returns: Action result with updated events and series info.
Inputs: event_id (required). Returns: object
mark_task_completeC
Mark a task as complete.
Args: task_id: The task ID to mark as complete
Returns: Updated task object
Inputs: task_id (required). Returns: object
prioritize_taskB
Prioritize a task (elevates to high priority, triggers rescheduling).
Args: task_id: The task ID to prioritize
Returns: Planner action result with updated task state
Inputs: task_id (required). Returns: object
reschedule_focus_blockC
Reschedule a focus time block to a different time.
Args: calendar_id: The calendar ID containing the focus block event_id: The focus block event ID to reschedule start_time: New start time in ISO format (optional, triggers AI reschedule if not provided) end_time: New end time in ISO format (optional)
Returns: Planner action result with updated event state.
Inputs: calendar_id (required), event_id (required), start_time, end_time. Returns: object
restart_taskB
Restart a completed/archived task (returns it to active scheduling).
Args: task_id: The task ID to restart
Returns: Planner action result with updated task state
Inputs: task_id (required). Returns: object
skip_habitA
Skip a habit instance.
Use this to skip today's scheduled habit event without marking it done.
Args: event_id: The event ID of the specific habit instance to skip
Returns: Action result with updated events and series info.
Inputs: event_id (required). Returns: object
start_taskC
Start working on a task (marks as IN_PROGRESS and starts timer).
Args: task_id: The task ID to start working on
Returns: Planner action result with updated task state
Inputs: task_id (required). Returns: object
stop_taskA
Stop working on a task (pauses timer, keeps task active).
Args: task_id: The task ID to stop working on
Returns: Planner action result with updated task state
Inputs: task_id (required). Returns: object
unlock_focus_blockA
Unlock a focus time block to allow it to be rescheduled.
Args: calendar_id: The calendar ID containing the focus block event_id: The focus block event ID to unlock
Returns: Planner action result with updated event state.
Inputs: calendar_id (required), event_id (required). Returns: object
update_focus_settingsB
Update focus time settings.
Args: settings_id: The focus settings ID to update min_duration_mins: Minimum focus block duration in minutes ideal_duration_mins: Ideal focus block duration in minutes max_duration_mins: Maximum focus block duration in minutes defense_aggression: Protection level (NONE, LOW, MEDIUM, HIGH, MAX) enabled: Whether focus time is enabled
Returns: Updated focus settings.
Inputs: settings_id (required), min_duration_mins, ideal_duration_mins, max_duration_mins, +2 more. Returns: object
update_habitB
Update an existing smart habit.
Args: lineage_id: The habit lineage ID to update title: New title (optional) ideal_time: New preferred time in "HH:MM" format (optional) duration_min_mins: New minimum duration in minutes (optional) duration_max_mins: New maximum duration in minutes (optional) enabled: Enable/disable the habit (optional) frequency: New frequency (DAILY, WEEKLY, MONTHLY, YEARLY) (optional) ideal_days: New ideal days list (optional) event_type: New event type (optional) defense_aggression: New defense aggression (optional) description: New description (optional)
Returns: Updated habit object.
Inputs: lineage_id (required), title, ideal_time, duration_min_mins, +7 more. Returns: object
update_taskB
Update an existing task in Reclaim.ai.
Args: task_id: The task ID to update title: New title (optional) duration_minutes: New duration in minutes (optional) due_date: New due date in ISO format (optional) status: New status - NEW, SCHEDULED, IN_PROGRESS, COMPLETE (optional)
Returns: Updated task object
Inputs: task_id (required), title, duration_minutes, due_date, +1 more. Returns: object
verify_connectionA
Verify API connection by fetching current user info.
Returns: Connection status with user details (id, email, name).
Inputs: no named parameters. Returns: object
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 32 tools
Most tools have distinct purposes targeting specific resources (tasks, habits, events, focus blocks) with clear action verbs, but some overlap exists between list_events and list_personal_events (both list events) and between mark_habit_done/skip_habit (both modify habit instances). Descriptions help clarify differences, but an agent might occasionally confuse these pairs.
Tool names follow a highly consistent verb_noun pattern throughout, using snake_case exclusively (e.g., create_task, list_habits, update_focus_settings). The pattern is predictable with verbs like create, get, list, update, delete, mark, start, stop, lock, unlock, reschedule, prioritize, restart, skip, enable, disable, and verify, making the set easy to navigate.
With 32 tools, the count feels heavy for a task/habit/calendar management server, bordering on excessive. While the domain is broad (covering tasks, habits, events, focus time, analytics, and settings), some tools could potentially be consolidated (e.g., mark_habit_done and skip_habit), making the surface more complex than necessary for typical agent workflows.
The tool set provides comprehensive CRUD/lifecycle coverage for all core domains: tasks (create, get, list, update, delete, complete, restart, prioritize, start, stop, add_time), habits (create, get, list, update, delete, enable, disable, mark_done, skip), events (list, get), focus blocks (lock, unlock, reschedule, update_settings), and analytics (user, focus). No obvious gaps exist, enabling full agent interaction with Reclaim.ai's features.
Maintenance
Related MCP Connectors
Official MCP server for subfeed.app — the cloud for agents. 15+ tools for AI agents to register, build, and deploy other agents. Zero human required. Start here: subfeed.app/skill.md
Official MCP server for Agentwork — delegate tasks to AI agents with human-in-the-loop
Official Miro MCP server - Supports context to code and creating diagrams, docs, and data tables.
Official MCP server for Qase — manage test cases, runs, suites, defects via AI tools.
Related MCP Servers
- AlicenseNot gradedqualityDmaintenanceThis server provides a standardized framework using the Model Context Protocol (MCP) to seamlessly integrate and manage diverse tools, enabling features like Twitter automation, cryptocurrency updates, and ElizaOS interaction.2MIT
- AlicenseNot gradedqualityDmaintenanceOfficial MCP server for PostIdentity - Generate AI-powered social media posts, threads, and replies from any MCP-compatible AI assistant with identity management and refinement capabilities.1MIT
- AlicenseAqualityCmaintenanceEnables MCP-compatible clients to manage Reclaim.ai tasks, including listing, creating, updating, completing, deleting, and timer operations through natural language.1313 npm19MIT
- AlicenseAqualityDmaintenanceMCP server that connects AI agents to calendars, bookings, and scheduling polls via the Model Context Protocol.2210 npmMIT