amazing-marvin-complete-mcp

An MCP (Model Context Protocol) server for Amazing Marvin with complete coverage of the public API: 38 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 (38)

Capability overview

list_capabilities (no Marvin API call) returns the same map as the table below, per tool with can and cannot, plus the list of things that only work in the app. Call it before assuming something is impossible via MCP. The server also sends a short instructions text at initialize (shown by Claude Code, not by the claude.ai clients). The first line of every tool description is a whole sentence of at most 75 characters stating the capability — the clients show only that line in their catalog; the test tests/test_discoverability.py guards it.

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:

git clone <this repo> && cd amazing-marvin-complete-mcp
python -m venv .venv && .venv/bin/pip install .
# then use /path/to/.venv/bin/marvin-mcp as the command below

Local (stdio) — Claude Desktop, Claude Code, any MCP client

The default transport is stdio, so the client starts the server itself:

{
  "mcpServers": {
    "amazing-marvin": {
      "command": "uvx",
      "args": ["amazing-marvin-complete-mcp"],
      "env": {
        "MARVIN_API_TOKEN": "…",
        "MARVIN_FULL_ACCESS_TOKEN": "…",
        "MARVIN_TIMEZONE": "Europe/Stockholm"
      }
    }
  }
}

(For Claude Code: claude mcp add amazing-marvin -e MARVIN_API_TOKEN=… -- uvx amazing-marvin-complete-mcp.)

Remote (Streamable HTTP)

MCP_TRANSPORT=http PORT=8787 MCP_AUTH_TOKEN_FILE=/path/to/token \
MARVIN_API_TOKEN_FILE=/path/to/api-token .venv/bin/marvin-mcp

The MCP endpoint is /mcp. HTTP mode fails closed: without MCP_AUTH_TOKEN (or MCP_AUTH_TOKEN_FILE) the server refuses to start, with instructions in the error message; set MCP_ALLOW_UNAUTHENTICATED=true only to deliberately run an open instance on localhost. The built-in bearer check protects every path but is an internal barrier, not a complete auth story: put a reverse proxy with TLS in front, and for Claude custom connectors an OAuth 2.1-capable MCP auth proxy. A Dockerfile for HTTP mode is included (runs as a non-root user; mount a volume on /data to persist the daily rate-limit counter across restarts).

Configuration

All settings via environment variables — see .env.example for the full annotated list. Highlights: every secret supports a *_FILE variant (recommended); MARVIN_TIMEZONE should match the timezone your Marvin account lives in (defaults to the system timezone, which is UTC in most containers).

Rate limiting

Marvin's documented limits — 1 write/second, 1 read/3 seconds, 1440 calls/day — are enforced by a single process-global queue shared by all tools and sessions, with margin (1.1 s / 3.1 s). The daily counter persists across restarts (STATE_DIR) and rolls over at midnight in the configured timezone. get_rate_limit_status shows today's usage.

Marvin API quirks & findings

Everything below was verified against the live API (2026-08-19 through 2026-08-29). This is the half of the repo you can use without running it.

Habits

• Non-raw GET /habits does not read your habit documents. It reads a server-side tracking registry that is created lazily on the first recording — a habit that has never been recorded is missing from the response entirely, and the entries carry no titles (only habitId + history). Use ?raw=1 (Full Access Token) to list actual habit documents. GET /habit?id=… returns the tracking record — history but no title.
• POST /updateHabit rejects integers serialized as floats: "value": 1.0 → 400 Bad request, "value": 1 → 200. Send ints as ints.

Tasks & projects

• POST /markDone works for tasks only — projects get 400 "Can only mark Tasks done with this API".
• By default /addTask parses some of Marvin's quick-add shortcut syntax server-side: ~15 becomes a 15-minute timeEstimate, +YYYY-MM-DD sets day (scheduling — not the deadline) and *p1..*p3 set priority. All three are stripped from the title. Note the priority mapping is inverted relative to the stored field: *p1 (highest) → isStarred: 3, *p2 → 2, *p3 (lowest) → isStarred: 1. The other magic words (*urgent, *fire, *heavy, *weight, *love, *lowfocus, *physical) and $-words (e.g. $MONTH on a non-recurring task) are not parsed — they are stored literally in the title with no fields set; they only work in the app's quick-add. But the # shortcut is outright dangerous: any #word in the title (a ticket reference like #123 included) is stored literally as parentId (greedy up to the first hyphen, e.g. #MCP-TEST → parentId: "#MCP" and a corrupted title) without resolving any ID — even overriding an explicitly supplied parentId in the same request. The task then lives outside every category and outside the Inbox — effectively invisible. (First reported by lucasoeth/marvin-mcp; independently reproduced and expanded here.) This server is not affected: create_task sends the undocumented X-Auto-Complete: false header (added in MarvinAPI#50), which disables all shortcut parsing — titles are stored verbatim, and the time_estimate_minutes parameter replaces the ~15 shortcut (timeEstimate is milliseconds: 15 min = 900000).
• /addProject has the same #word corruption bug but ignores the X-Auto-Complete header (live-tested: the title is stripped and parentId corrupted even with the header set). This server therefore blocks # in project titles locally (in the client layer, before any API call) with an explanatory error. Category titles are safe — they go through /doc/create, which parses nothing.
• /addEvent is unaffected (live-tested 2026-08-25): event titles with #word are stored verbatim, with and without the header — the quick-add parsing bug exists only in /addTask and /addProject.
• Generated instances of recurring tasks have deterministic IDs (YYYY-MM-DD_<recurringTaskId>), which is why marking them done/undone through the API cannot create duplicates. The instances are generated by the Marvin client, so today's recurring tasks can be missing from /todayItems until the app has been running.
• /doc/update can sporadically return a transient 500; the write is atomic (no partial state) — just retry. Project renames, moves, label changes etc. all work through it.
• /doc/update returns 500 instead of 404 for documents that do not exist (deleted or never created; live-tested 2026-08-29) — a permanent 500 therefore means "wrong/dead ID", not a server error or a corrupted document.
• startDate/endDate are ignored by /addTask and /addProject (live-tested 2026-08-29) — they can only be set afterwards via /doc/update (the update tools). /addProject also ignores color/icon (set them via update_category_or_project), and /addTask silently drops noAutoOrbit (live-tested 2026-09-13) — set it with update_task after creating the task.
• A clock time on a task (Time/taskTime) is set in the app, not via this MCP — a deliberate MCP choice (the double-write sync, see set_reminder), NOT a Marvin limitation: Marvin fully supports times on tasks, and with auto-created reminders a set Time automatically becomes a reminder at the same time (live data 2026-09-02). Reading the fields works. The phrasing "you cannot set a time on a task" is therefore wrong about Marvin — it only holds for the MCP write path.
• Projects are prioritized with the string field priority ("high"/"mid"/"low"), not isStarred like tasks (live-tested 2026-08-29) — which is why set_priority is task-only. Mapping (verified against the app's code 2026-08-30): high = Most important (red), mid = Very important (orange), low = Important (yellow, the one-star level). The app's fourth level Low priority (down arrow) is stored on tasks as isStarred: -1 (magic words *low/*p0); projects do not have it — the app clears the priority when converting a low priority task into a project. set_priority/create_task accept -1.
• Completed tasks are readable via the undocumented endpoint GET /doneItems?date=YYYY-MM-DD (missing from the OpenAPI spec and the wiki; live-tested 2026-08-30, may disappear without notice). It filters on the task's day, not on doneAt, and a past day survives completion both in the app and via /markDone (the app sets day to today only on unscheduled and future-dated tasks). get_done_items therefore fetches the date plus a 7-day lookback window and filters on doneAt; the response states its coverage (covers_from, days_fetched), complete results are cached for 30 minutes, and on a 429 the tool returns what it got, flagged incomplete/days_missing. Single completed tasks can also be read with /doc?id=. /todayItems, /dueItems and /children exclude completed items; /doneTasks and /completedItems are 404.
• Marvin returns 429 even with 3 s spacing when the daily average (1440/day = "1 per minute") is exceeded within a shorter, undocumented window — observed 2026-08-30 after ~100 calls in one hour. After a 429 the limiter pauses all calls for 60 s (or Retry-After) and logs the response headers (allow-listed names only).
• The server validates no writes (live-tested 2026-08-29): invalid dates, negative/out-of-range numbers, mistyped values, empty titles, dead parentId/labelIds and unknown fields are stored verbatim via /doc/update (and almost everything via /addTask). The tools therefore validate dates (strict YYYY-MM-DD, year 2000-2100), titles and numeric ranges client-side; references are not validated (orphan risk documented in the descriptions).
• /doc/delete responds 200 even for IDs that never existed or are already deleted — idempotent, no 404 (unlike /doc/update). /markDone on the other hand gives a proper 404 for a missing ID and 400 for an already completed task — three endpoints, three different answers to "does not exist" (live-tested 2026-08-29).
• Read endpoints (/todayItems, /dueItems) are pure date filters: backburner, startDate and orphan status (dead parentId) do not affect them — and orphans never show up under unassigned (live-tested 2026-08-29). /todayItems?date=X returns all open items with day <= X, not just day X (live-tested 2026-09-11, rollover enabled). /markDone stops running time tracking and now also writes task.times (live-tested 2026-09-02; it did not on 2026-08-29 — server behavior changed). A direct /track STOP still does not write times; there /tracks is the only record.
• orbit/noAutoOrbit are missing from the wiki's data types but present in live data (bool, verified 2026-08-29) — exposed as explicitly undocumented passthrough parameters on the update tools.
• Project↔category conversion happens in place: _id, createdAt and the children remain (verified 2026-08-29, both via an app field test and via the API). The app has two conversion paths with different behavior (verified 2026-08-30/31): the Edit Settings button permanently clears day/dueDate/priority/isFrogged and leaves firstScheduled behind (a bug in Marvin's tracker), while the right-click/hover path is a lossless round trip — but that button is not in the menu by default (add it via the gear icon in the right-click menu → Add action). convert_category_or_project is lossless by default since 1.5.0; pass clear_project_fields=True for a clean category (the previous values are returned in removed_project_fields). There is no official conversion endpoint — the tool sets type directly, which is undocumented server behavior and marked experimental.
• /doc/create does not echo back a server-generated _id — supply your own if you need to reference the document afterwards.
• Deletion via /doc/delete is permanent; Marvin's trash is client-side.
• The app's view after API writes (live-tested 2026-09-12, PWA + Windows desktop app 1.70.0, both open at the same time): creating, field changes and moves between category/Inbox render immediately with no action needed. Deletions do not render at all — neither waiting nor switching views helps. The same held for a cleared plannedWeek/plannedMonth with Planning Ahead on (2026-08-29) and for strategy toggling (method rule since 2026-08-29). Rule of action: (1) confirm the server with a read (get_children on the parent — the task should be missing); (2) if the app still shows the row, that is the app's view, not an error — reload the client before the row is touched in the app: F5 in the web app/PWA, restart of the desktop app (it has no refresh). The reason for "before the row is touched": editing a row in the app whose document is already deleted on the server can recreate the document through the client's conflict resolution (observed once, 2026-09-12, in one of the two clients — which one is not recorded; reported upstream). This is the Marvin client's view — not to be confused with get_done_items' own 30-minute cache, which goes the other way (app → MCP).

Reward points & kudos

• Kudos (XP/level, read via /kudos) and reward points (claim/unclaim/spend/reset) are two separate systems. /kudos lacks nextMultiplier (MarvinAPI issue #5) — it's in /me.
• /markDone does not award a task's reward points (cf. issue #6 for kudos) — claimRewardPoints is a separate call.
• A MANUAL claim (itemId: "MANUAL") cannot be undone: the server stores no entry for it, so /unclaimRewardPoints returns 404 "No such entry" (with or without a points field), and claiming negative points is rejected with 400. The Marvin web app never uses MANUAL — it is an API-only facility. The only compensation is spending the same amount, which inflates the spent statistics.
• /spendRewardPoints returns a 500 if the balance would go negative.
• The app's purchasable rewards are separate db="Rewards" documents that the public API cannot reach at all (live-tested 2026-08-29: /rewards and every variant 404, no rewards profile documents, and /doc needs an ID you can't discover). The Task field isReward is decoupled from the app's reward flow and produced no UI effect when set via the API.

Reminders

• A task reminder in Marvin is two writes that only the app keeps in sync: reminder fields on the task document (taskTime, reminderTime, reminderOffset, snooze, autoSnooze) and a server-side entry via /reminder/set. Writing only one side (all the API lets you do comfortably) produces entries the app UI won't show on the task, or server-side orphans. Standalone reminders (type M) are the safe use of the API. (Risk first documented by Recon2026/marvin-mcp; confirmed by the official wiki's own warning.)

Time & planning

• /todayTimeBlocks omits the block↔category link (issue #65); this server recovers the mapping from the strategySettings.plannerSmartLists profile document.
• Stopping time tracking via a direct /track STOP does not update the task's own times/duration fields; /tracks is the source of truth. /markDone during active tracking does write both times (live-tested 2026-09-02) and duration (verified 2026-09-13; the app shows the tracked time under Completed Today when Time Tracking is on).
• Calendar events created via /addEvent sync onwards only while the Marvin app is running somewhere (client-side calendar sync).

UI behavior of API-set fields (verified in the app, 2026-08-29)

• Toggling a strategy requires an app restart before its fields render — without one, freshly enabled strategies show nothing and look broken.
• backburner is only effective on unscheduled items: scheduling (day) trumps the flag in the UI. Set day: "unassigned" together with backburner: true.
• startDate hides backburner items until their start date (the Start Dates strategy's actual mechanic) — it does not hide scheduled tasks.
• Icon names are library-prefixed (lucide-Rocket, huge-happy) or emoji. Projects render their icon only when Master List → Configure View → "Show Custom Icon On" includes projects — "Categories & Projects" (verified 2026-08-31) or "Just Projects" (verified 2026-09-18); the earlier "projects never render an own icon" was our own test error.
• A project's timeEstimate renders as its own estimate; the UI does not aggregate it with the children's estimates, despite the wiki's claim.
• Snoozed tasks (itemSnoozeTime) are hidden from the category view too — the wiki's "everywhere except the master list" doesn't hold there.
• timeBlockSection links a task to a time block's section in Today — but only if the Time Block Sections strategy is on, the day view is grouped by time block (Group by → Group by time block section; set per device, not synced) and the task is scheduled on the block's day. Unscheduled tasks with the field set do not appear in Today at all. The block needs no label/category mapping of its own; that mapping (Smart Time Block) is a second, independent route. Verified in the app 2026-09-17 (1.70.0.0, PWA + desktop); the earlier "stored but not rendered" finding was our own test error (grouping never set) and is withdrawn; the correction to Marvin support is pending. Since 1.7.0 create_time_block returns time_block_id (set client-side, as /doc/create does not echo the server id), usable directly as time_block_section.
• reviewDate shows in the Review view; the day-view banner additionally requires the "Review Alert" workflow snippet.
• Auto-orbit (if enabled) pulls newly scheduled tasks into Orbit unless noAutoOrbit is set.
• Project-only fields (day, dueDate, priority, isFrogged) written onto a category are silently accepted by the server (live-tested 2026-09-11). update_category_or_project still type-checks and blocks them, for a structural reason: a category is never completed, so those fields belong to projects and tasks. labelIds is different — categories have labels in the same field as projects, and an API-set label is stored and rendered (live-tested + verified in the app 2026-09-11), so label_ids is allowed on categories since 1.6.0.

How this differs from existing alternatives

Several good Amazing Marvin MCP servers exist; this one was built fresh (no shared code) after studying them, with a different goal — complete coverage of the public API rather than a curated subset:

• bgheneti/Amazing-Marvin-MCP — the established Python server; broad but not complete coverage, no global rate limiting.
• Recon2026/marvin-mcp — smaller scope (19 tools), unusually careful research; chose to make reminders read-only over the two-write risk. This server ships reminder writes with explicit warnings instead.
• lucasoeth/marvin-mcp — a different philosophy: a handful of consolidated workflow tools (brief/ capture/…) rather than an API mirror, plus direct CouchDB reads for search and completed tasks (which the public API can't do at all). If you want opinionated workflows or search, use theirs; if you want raw, complete API access with the sharp edges documented, use this one.
• LucaDeLeo/amazing-marvin-mcp — a Limited-API subset.

Credits & sources

No code was copied from any of these — the build is fresh — but they materially shaped it:

• amazingmarvin/MarvinAPI (+ wiki) — the official API documentation, OpenAPI spec, data types, and issue tracker this server is built against.
• bgheneti/Amazing-Marvin-MCP — architecture inspiration, endpoint reference during the initial gap analysis, and the MIT-licensing precedent.
• Recon2026/marvin-mcp — the reminder two-write integrity risk and the groundwork on recurring-task instances, both verified and documented here.
• lucasoeth/marvin-mcp — the #Category shortcut bug (reproduced here) and the insight that Marvin's sync database is a real CouchDB usable for reads.
• LucaDeLeo/amazing-marvin-mcp — the pointer that /addTask parses shortcut syntax server-side (partly confirmed, partly refuted — see the #Category finding), and the idea of MCP tool annotations.

Built with Claude Code (Claude Fable 5).

License

MIT.