Amazing Marvin (complete)

amazing-marvin-complete-mcp

An MCP (Model Context Protocol) server for Amazing Marvin with complete coverage of the public API: 50 tools over the 38 endpoints on Marvin's API endpoints page (read 2026-10-12; all but two, see below), 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 (50)

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. The same test keeps every description and the instructions text under 2,048 characters — Claude Code silently truncates longer text since v2.1.280.

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

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 — no bursts faster than one request every 3 seconds, bulk creation at one per second, 1440 calls/day — are enforced by a single process-global queue shared by all tools and sessions, with margin: only creating calls (/addTask, /addProject, /addEvent, /doc/create) use 1.1 s; everything else (reads, updates, /markDone, deletions) waits 3.1 s. The spacing is set by the kind of the call about to be made. After a 429 all calls pause 60 s (or Retry-After). The daily counter and the time of the last call persist across restarts (STATE_DIR) and the counter rolls over at midnight in the configured timezone. get_rate_limit_status shows today's usage and how long ago the last call went out. Multi-step tools (chains) retry a step once after a 500 or 429 and report which steps were done if they still fail.

Marvin API quirks & findings

Everything below was verified against the live API (2026-08-19 through 2026-10-12). 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#