Amazing Marvin Complete Mcp

No install snippet on purpose. A working MCP config is a command, its arguments and an environment block — the last two are where API keys live, so this catalogue never stores them and cannot publish them. Follow the link above for the authors' own instructions.

An MCP (Model Context Protocol) server for Amazing Marvin with complete coverage of the public API: 37 tools over all ~31 documented endpoints (plus the undocumented /doneItems), a global rate limiter that respects Marvin's documented limits, least-privilege token routing, and MCP tool annotations. As of 1.1.0 every writable field in Marvin's official data model (Tasks and Categories/Projects) is either supported by a tool or explicitly documented as unsupported — see docs/field-reconciliation.md. Every non-obvious behavior claim in the tool descriptions was verified against the live API — the findings are documented below in Marvin API quirks & findings, which may be useful even if you never run this server.

Maintenance status: Bug reports are welcome and appreciated — they help keep this working for everyone. Please note this is a side project maintained when time allows: bug reports get looked at, but response times vary and feature requests are unlikely to be picked up. For installation help, paste this README into your AI assistant — it can walk you through setup and troubleshooting far faster than I can. Provided as-is, without guarantees — it's MIT, fork freely.

Tools (37)

Group	Tools
Core	`test_connection`, `create_task`, `mark_done`, `unmark_done`, `update_task`, `set_priority`, `delete_task`
Reading	`get_today_items`, `get_due_items`, `get_done_items`, `get_children`, `get_categories`
Structure	`create_category_or_project`, `update_category_or_project`, `convert_category_or_project` (experimental)
Habits	`list_habits`, `get_habit`, `record_habit`
Time blocks	`get_today_time_blocks`, `create_time_block` (experimental)
Time tracking	`get_tracked_item`, `start_tracking`, `stop_tracking`, `get_time_tracks`
Kudos/rewards	`get_kudos`, `claim_reward_points`, `unclaim_reward_points`, `spend_reward_points`, `reset_reward_points`
Misc	`get_labels`, `get_goals`, `get_reminders`, `set_reminder`, `delete_reminder`, `create_event` (experimental), `get_account_info`, `get_rate_limit_status`

Deliberately not included: Smart List / task-picking logic (Marvin's own Spotlight does the picking; the server gives your assistant hands, not opinions), and the /reminder/deleteAll endpoint — the one documented endpoint without a tool, deliberately: it wipes every reminder in a single call and delete_reminder already covers targeted cleanup.

Every tool carries MCP tool annotations (readOnlyHint, destructiveHint, idempotentHint, openWorldHint) so capable clients can treat delete_task and reset_reward_points with the respect they deserve.

Getting your Marvin tokens

Both tokens live in Amazing Marvin under Settings → API (app.amazingmarvin.com/pre?api):

API Token (MARVIN_API_TOKEN, required for use) — limited access; enough for reading and creating tasks. The server does start without it (so MCP clients and directories can list the tools), but every tool call returns a clear error until the token is set.
Full Access Token (MARVIN_FULL_ACCESS_TOKEN, optional but recommended) — required by all /doc*-based tools: update_task, set_priority, unmark_done, delete_task, category creation, time blocks, list_habits, reminders, reset_reward_points.

Treat them like passwords; see SECURITY.md.

Install & run

Requires Python 3.12+.

From PyPI (recommended): with uv installed there is nothing to set up — point your MCP client at uvx amazing-marvin-complete-mcp as shown below.

From source: