The full upstream README, mirrored here for reference. Install config, tool schemas, adoption signals, and an original overview live on the Amazing Marvin (complete) listing page.
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.
| 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.
Both tokens live in Amazing Marvin under Settings → API (app.amazingmarvin.com/pre?api):
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.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.
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:
The default transport is stdio, so the client starts the server itself:
(For Claude Code: claude mcp add amazing-marvin -e MARVIN_API_TOKEN=… -- uvx amazing-marvin-complete-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).
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).
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.
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
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"./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.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).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.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.Retry-After) and logs the
response headers (allow-listed names only)./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)./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). /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._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./doc/delete is permanent; Marvin's trash is client-side.Reward points & kudos
/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.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.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
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.times/duration fields; /tracks is the source of truth./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)
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.lucide-Rocket, huge-happy) or emoji.
Projects never render an own icon — the app offers the picker but only
the color is used.timeEstimate renders as its own estimate; the UI does
not aggregate it with the children's estimates, despite the wiki's claim.itemSnoozeTime) are hidden from the category view too —
the wiki's "everywhere except the master list" doesn't hold there.timeBlockSection is stored but shows no visible section link in Today.reviewDate shows in the Review view; the day-view banner additionally
requires the "Review Alert" workflow snippet.noAutoOrbit is set.update_category_or_project type-checks before writing them.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:
No code was copied from any of these — the build is fresh — but they materially shaped it:
#Category shortcut bug (reproduced here) and the insight that Marvin's
sync database is a real CouchDB usable for reads./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).
MIT.