{
  "markdown": "# amazing-marvin-complete-mcp\n\n<!-- mcp-name: io.github.andreasd083/amazing-marvin-complete-mcp -->\n\nAn MCP ([Model Context Protocol](https://modelcontextprotocol.io)) server for\n[Amazing Marvin](https://amazingmarvin.com) with **complete coverage of the\npublic API**: 37 tools over all ~31 documented endpoints (plus the\nundocumented `/doneItems`), a global rate\nlimiter that respects Marvin's documented limits, least-privilege token\nrouting, and MCP tool annotations. As of 1.1.0 every writable field in\nMarvin's official data model (Tasks and Categories/Projects) is either\nsupported by a tool or explicitly documented as unsupported — see\n[docs/field-reconciliation.md](docs/field-reconciliation.md). Every\nnon-obvious behavior claim in the tool descriptions was verified against\nthe live API — the findings are documented below in\n[Marvin API quirks & findings](#marvin-api-quirks--findings),\nwhich may be useful even if you never run this server.\n\n> **Maintenance status:** Bug reports are welcome and appreciated — they\n> help keep this working for everyone. Please note this is a side project\n> maintained when time allows: bug reports get looked at, but response\n> times vary and feature requests are unlikely to be picked up. For\n> installation help, paste this README into your AI assistant — it can walk\n> you through setup and troubleshooting far faster than I can. Provided\n> as-is, without guarantees — it's MIT, fork freely.\n\n## Tools (37)\n\n| Group | Tools |\n|---|---|\n| Core | `test_connection`, `create_task`, `mark_done`, `unmark_done`, `update_task`, `set_priority`, `delete_task` |\n| Reading | `get_today_items`, `get_due_items`, `get_done_items`, `get_children`, `get_categories` |\n| Structure | `create_category_or_project`, `update_category_or_project`, `convert_category_or_project` (experimental) |\n| Habits | `list_habits`, `get_habit`, `record_habit` |\n| Time blocks | `get_today_time_blocks`, `create_time_block` (experimental) |\n| Time tracking | `get_tracked_item`, `start_tracking`, `stop_tracking`, `get_time_tracks` |\n| Kudos/rewards | `get_kudos`, `claim_reward_points`, `unclaim_reward_points`, `spend_reward_points`, `reset_reward_points` |\n| Misc | `get_labels`, `get_goals`, `get_reminders`, `set_reminder`, `delete_reminder`, `create_event` (experimental), `get_account_info`, `get_rate_limit_status` |\n\nDeliberately **not** included: Smart List / task-picking logic (Marvin's own\nSpotlight does the picking; the server gives your assistant hands, not\nopinions), and the `/reminder/deleteAll` endpoint — the one documented\nendpoint without a tool, deliberately: it wipes every reminder in a single\ncall and `delete_reminder` already covers targeted cleanup.\n\nEvery tool carries [MCP tool annotations](https://modelcontextprotocol.io/specification/2025-06-18/server/tools#tool-annotations)\n(`readOnlyHint`, `destructiveHint`, `idempotentHint`, `openWorldHint`) so\ncapable clients can treat `delete_task` and `reset_reward_points` with the\nrespect they deserve.\n\n## Getting your Marvin tokens\n\nBoth tokens live in Amazing Marvin under **Settings → API**\n([app.amazingmarvin.com/pre?api](https://app.amazingmarvin.com/pre?api)):\n\n- **API Token** (`MARVIN_API_TOKEN`, required for use) — limited access;\n  enough for reading and creating tasks. The server does start without it\n  (so MCP clients and directories can list the tools), but every tool call\n  returns a clear error until the token is set.\n- **Full Access Token** (`MARVIN_FULL_ACCESS_TOKEN`, optional but\n  recommended) — required by all `/doc*`-based tools: `update_task`,\n  `set_priority`, `unmark_done`, `delete_task`, category creation, time\n  blocks, `list_habits`, reminders, `reset_reward_points`.\n\nTreat them like passwords; see [SECURITY.md](SECURITY.md).\n\n## Install & run\n\nRequires Python 3.12+.\n\n**From PyPI** (recommended): with [uv](https://docs.astral.sh/uv/) installed\nthere is nothing to set up — point your MCP client at\n`uvx amazing-marvin-complete-mcp` as shown below.\n\n**From source:**\n\n```bash\ngit clone <this repo> && cd amazing-marvin-complete-mcp\npython -m venv .venv && .venv/bin/pip install .\n# then use /path/to/.venv/bin/marvin-mcp as the command below\n```\n\n### Local (stdio) — Claude Desktop, Claude Code, any MCP client\n\nThe default transport is stdio, so the client starts the server itself:\n\n```json\n{\n  \"mcpServers\": {\n    \"amazing-marvin\": {\n      \"command\": \"uvx\",\n      \"args\": [\"amazing-marvin-complete-mcp\"],\n      \"env\": {\n        \"MARVIN_API_TOKEN\": \"…\",\n        \"MARVIN_FULL_ACCESS_TOKEN\": \"…\",\n        \"MARVIN_TIMEZONE\": \"Europe/Stockholm\"\n      }\n    }\n  }\n}\n```\n\n(For Claude Code: `claude mcp add amazing-marvin -e MARVIN_API_TOKEN=… --\nuvx amazing-marvin-complete-mcp`.)\n\n### Remote (Streamable HTTP)\n\n```bash\nMCP_TRANSPORT=http PORT=8787 MCP_AUTH_TOKEN_FILE=/path/to/token \\\nMARVIN_API_TOKEN_FILE=/path/to/api-token .venv/bin/marvin-mcp\n```\n\nThe MCP endpoint is `/mcp`. HTTP mode **fails closed**: without\n`MCP_AUTH_TOKEN` (or `MCP_AUTH_TOKEN_FILE`) the server refuses to start,\nwith instructions in the error message; set `MCP_ALLOW_UNAUTHENTICATED=true`\nonly to deliberately run an open instance on localhost. The built-in bearer\ncheck protects every path but is an internal barrier, not a complete auth\nstory:\nput a reverse proxy with TLS in front, and for Claude custom connectors an\nOAuth 2.1-capable MCP auth proxy. A `Dockerfile` for HTTP mode is included\n(runs as a non-root user; mount a volume on `/data` to persist the daily\nrate-limit counter across restarts).\n\n### Configuration\n\nAll settings via environment variables — see [.env.example](.env.example)\nfor the full annotated list. Highlights: every secret supports a `*_FILE`\nvariant (recommended); `MARVIN_TIMEZONE` should match the timezone your\nMarvin account lives in (defaults to the system timezone, which is UTC in\nmost containers).\n\n### Rate limiting\n\nMarvin's documented limits — 1 write/second, 1 read/3 seconds, 1440\ncalls/day — are enforced by a single process-global queue shared by all\ntools and sessions, with margin (1.1 s / 3.1 s). The daily counter persists\nacross restarts (`STATE_DIR`) and rolls over at midnight in the configured\ntimezone. `get_rate_limit_status` shows today's usage.\n\n## Marvin API quirks & findings\n\nEverything below was verified against the live API (2026-08-19 through\n2026-08-29). This is the half of the repo you can use without running it.\n\n**Habits**\n- Non-raw `GET /habits` does **not** read your habit documents. It reads a\n  server-side tracking registry that is created *lazily on the first\n  recording* — a habit that has never been recorded is missing from the\n  response entirely, and the entries carry no titles (only `habitId` +\n  history). Use `?raw=1` (Full Access Token) to list actual habit documents.\n  `GET /habit?id=…` returns the tracking record — history but no title.\n- `POST /updateHabit` rejects integers serialized as floats:\n  `\"value\": 1.0` → 400 Bad request, `\"value\": 1` → 200. Send ints as ints.\n\n**Tasks & projects**\n- `POST /markDone` works for tasks only — projects get\n  `400 \"Can only mark Tasks done with this API\"`.\n- By default `/addTask` parses *some* of Marvin's quick-add shortcut syntax\n  server-side: `~15` becomes a 15-minute `timeEstimate`, `+YYYY-MM-DD` sets\n  `day` (scheduling — **not** the deadline) and `*p1`..`*p3` set priority.\n  All three are stripped from the title. Note the priority mapping is\n  inverted relative to the stored field: `*p1` (highest) → `isStarred: 3`,\n  `*p2` → `2`, `*p3` (lowest) → `isStarred: 1`. The other magic words (`*urgent`,\n  `*fire`, `*heavy`, `*weight`, `*love`, `*lowfocus`, `*physical`) and\n  `$`-words (e.g. `$MONTH` on a non-recurring task) are **not** parsed —\n  they are stored literally in the title with no fields set; they only work\n  in the app's quick-add.\n  But the `#` shortcut is outright dangerous: **any** `#word` in the title\n  (a ticket reference like `#123` included) is stored literally as\n  `parentId` (greedy up to the first hyphen, e.g. `#MCP-TEST` →\n  `parentId: \"#MCP\"` and a corrupted title) without resolving any ID —\n  **even overriding an explicitly supplied `parentId` in the same request**.\n  The task then lives outside every category *and* outside the Inbox —\n  effectively invisible. (First reported by\n  [lucasoeth/marvin-mcp](https://github.com/lucasoeth/marvin-mcp);\n  independently reproduced and expanded here.)\n  **This server is not affected:** `create_task` sends the undocumented\n  `X-Auto-Complete: false` header (added in\n  [MarvinAPI#50](https://github.com/amazingmarvin/MarvinAPI/issues/50)),\n  which disables all shortcut parsing — titles are stored verbatim, and the\n  `time_estimate_minutes` parameter replaces the `~15` shortcut\n  (`timeEstimate` is milliseconds: 15 min = `900000`).\n- `/addProject` has the same `#word` corruption bug but **ignores the\n  `X-Auto-Complete` header** (live-tested: the title is stripped and\n  `parentId` corrupted even with the header set). This server therefore\n  blocks `#` in project titles locally (in the client layer, before any API\n  call) with an explanatory error. Category titles are safe — they go\n  through `/doc/create`, which parses nothing.\n- `/addEvent` is **unaffected** (live-tested 2026-08-25): event titles with\n  `#word` are stored verbatim, with and without the header — the quick-add\n  parsing bug exists only in `/addTask` and `/addProject`.\n- Generated instances of recurring tasks have deterministic IDs\n  (`YYYY-MM-DD_<recurringTaskId>`), which is why marking them done/undone\n  through the API cannot create duplicates. The instances are generated by\n  the Marvin *client*, so today's recurring tasks can be missing from\n  `/todayItems` until the app has been running.\n- `/doc/update` can sporadically return a transient 500; the write is\n  atomic (no partial state) — just retry. Project renames, moves, label\n  changes etc. all work through it.\n- `/doc/update` returns **500 instead of 404** for documents that do not\n  exist (deleted or never created; live-tested 2026-08-29) — a *permanent*\n  500 therefore means \"wrong/dead ID\", not a server error or a corrupted\n  document.\n- `startDate`/`endDate` are ignored by `/addTask` and `/addProject`\n  (live-tested 2026-08-29) — they can only be set afterwards via\n  `/doc/update` (the update tools). `/addProject` also ignores\n  `color`/`icon` (set them via `update_category_or_project`).\n- Projects are prioritized with the string field `priority`\n  (`\"high\"`/`\"mid\"`/`\"low\"`), not `isStarred` like tasks (live-tested\n  2026-08-29) — which is why `set_priority` is task-only. Mapping (verified\n  against the app's code 2026-08-30): `high` = Most important (red),\n  `mid` = Very important (orange), `low` = **Important** (yellow, the\n  one-star level). The app's fourth level *Low priority* (down arrow) is\n  stored on tasks as `isStarred: -1` (magic words `*low`/`*p0`); projects\n  do not have it — the app clears the priority when converting a low\n  priority task into a project. `set_priority`/`create_task` accept `-1`.\n- **Completed tasks are readable** via the **undocumented** endpoint\n  `GET /doneItems?date=YYYY-MM-DD` (missing from the OpenAPI spec and the\n  wiki; live-tested 2026-08-30, may disappear without notice). It filters\n  on the task's `day`, not on `doneAt`, and a past `day` survives\n  completion both in the app and via `/markDone` (the app sets `day` to\n  today only on unscheduled and future-dated tasks). `get_done_items`\n  therefore fetches the date plus a 7-day lookback window and filters on\n  `doneAt`; the response states its coverage (`covers_from`,\n  `days_fetched`), complete results are cached for 30 minutes, and on a\n  429 the tool returns what it got, flagged `incomplete`/`days_missing`.\n  Single completed tasks can also be read with `/doc?id=`. `/todayItems`,\n  `/dueItems` and `/children` exclude completed items; `/doneTasks` and\n  `/completedItems` are 404.\n- **Marvin returns 429 even with 3 s spacing** when the daily average\n  (1440/day = \"1 per minute\") is exceeded within a shorter, undocumented\n  window — observed 2026-08-30 after ~100 calls in one hour. After a 429\n  the limiter pauses all calls for 60 s (or `Retry-After`) and logs the\n  response headers (allow-listed names only).\n- **The server validates no writes** (live-tested 2026-08-29): invalid\n  dates, negative/out-of-range numbers, mistyped values, empty titles,\n  dead parentId/labelIds and unknown fields are stored verbatim via\n  `/doc/update` (and almost everything via `/addTask`). The tools therefore\n  validate dates (strict YYYY-MM-DD, year 2000-2100), titles and numeric\n  ranges client-side; references are not validated (orphan risk documented\n  in the descriptions).\n- `/doc/delete` responds 200 even for IDs that never existed or are already\n  deleted — idempotent, no 404 (unlike `/doc/update`). `/markDone` on the\n  other hand gives a proper 404 for a missing ID and 400 for an already\n  completed task — three endpoints, three different answers to \"does not\n  exist\" (live-tested 2026-08-29).\n- Read endpoints (`/todayItems`, `/dueItems`) are pure date filters:\n  backburner, startDate and orphan status (dead parentId) do not affect\n  them — and orphans never show up under `unassigned` (live-tested\n  2026-08-29). `/markDone` stops running time tracking and now also\n  writes `task.times` (live-tested 2026-09-02; it did not on 2026-08-29 —\n  server behavior changed). A direct `/track STOP` still does not write\n  `times`; there `/tracks` is the only record.\n- `orbit`/`noAutoOrbit` are missing from the wiki's data types but present\n  in live data (bool, verified 2026-08-29) — exposed as explicitly\n  undocumented passthrough parameters on the update tools.\n- Project↔category conversion happens **in place**: `_id`, `createdAt` and\n  the children remain (verified 2026-08-29, both via an app field test and\n  via the API). The app has two conversion paths with different behavior\n  (verified 2026-08-30/31): the Edit Settings button permanently clears\n  `day`/`dueDate`/`priority`/`isFrogged` and leaves `firstScheduled` behind\n  (a bug in Marvin's tracker), while the right-click/hover path is a\n  lossless round trip — but that button is not in the menu by default (add\n  it via the gear icon in the right-click menu → Add action).\n  `convert_category_or_project` is lossless by default since 1.5.0; pass\n  `clear_project_fields=True` for a clean category (the previous values are\n  returned in `removed_project_fields`). There is no official conversion\n  endpoint — the tool sets `type` directly, which is undocumented server\n  behavior and marked experimental.\n- `/doc/create` does not echo back a server-generated `_id` — supply your\n  own if you need to reference the document afterwards.\n- Deletion via `/doc/delete` is permanent; Marvin's trash is client-side.\n\n**Reward points & kudos**\n- Kudos (XP/level, read via `/kudos`) and reward points\n  (claim/unclaim/spend/reset) are two separate systems. `/kudos` lacks\n  `nextMultiplier` (MarvinAPI issue #5) — it's in `/me`.\n- `/markDone` does **not** award a task's reward points (cf. issue #6 for\n  kudos) — `claimRewardPoints` is a separate call.\n- A `MANUAL` claim (`itemId: \"MANUAL\"`) **cannot be undone**: the server\n  stores no entry for it, so `/unclaimRewardPoints` returns\n  `404 \"No such entry\"` (with or without a `points` field), and claiming\n  negative points is rejected with 400. The Marvin web app never uses\n  `MANUAL` — it is an API-only facility. The only compensation is spending\n  the same amount, which inflates the spent statistics.\n- `/spendRewardPoints` returns a 500 if the balance would go negative.\n- The app's purchasable rewards are separate `db=\"Rewards\"` documents that\n  the public API **cannot reach at all** (live-tested 2026-08-29: `/rewards`\n  and every variant 404, no rewards profile documents, and `/doc` needs an\n  ID you can't discover). The Task field `isReward` is decoupled from the\n  app's reward flow and produced no UI effect when set via the API.\n\n**Reminders**\n- A *task* reminder in Marvin is two writes that only the app keeps in\n  sync: reminder fields on the task document (`taskTime`, `reminderTime`,\n  `reminderOffset`, `snooze`, `autoSnooze`) **and** a server-side entry via\n  `/reminder/set`. Writing only one side (all the API lets you do\n  comfortably) produces entries the app UI won't show on the task, or\n  server-side orphans. Standalone reminders (type `M`) are the safe use of\n  the API. (Risk first documented by\n  [Recon2026/marvin-mcp](https://github.com/Recon2026/marvin-mcp);\n  confirmed by the official wiki's own warning.)\n\n**Time & planning**\n- `/todayTimeBlocks` omits the block↔category link (issue #65); this\n  server recovers the mapping from the `strategySettings.plannerSmartLists`\n  profile document.\n- Stopping time tracking via the API does not update the task's own\n  `times`/`duration` fields; `/tracks` is the source of truth.\n- Calendar events created via `/addEvent` sync onwards only while the\n  Marvin app is running somewhere (client-side calendar sync).\n\n**UI behavior of API-set fields (verified in the app, 2026-08-29)**\n- Toggling a strategy requires an app restart before its fields render —\n  without one, freshly enabled strategies show nothing and look broken.\n- `backburner` is only effective on unscheduled items: scheduling (`day`)\n  trumps the flag in the UI. Set `day: \"unassigned\"` together with\n  `backburner: true`.\n- `startDate` hides *backburner* items until their start date (the Start\n  Dates strategy's actual mechanic) — it does not hide scheduled tasks.\n- Icon names are library-prefixed (`lucide-Rocket`, `huge-happy`) or emoji.\n  Projects never render an own icon — the app offers the picker but only\n  the color is used.\n- A project's `timeEstimate` renders as its own estimate; the UI does\n  not aggregate it with the children's estimates, despite the wiki's claim.\n- Snoozed tasks (`itemSnoozeTime`) are hidden from the category view too —\n  the wiki's \"everywhere except the master list\" doesn't hold there.\n- `timeBlockSection` is stored but shows no visible section link in Today.\n- `reviewDate` shows in the Review view; the day-view banner additionally\n  requires the \"Review Alert\" workflow snippet.\n- Auto-orbit (if enabled) pulls newly scheduled tasks into Orbit unless\n  `noAutoOrbit` is set.\n- Project-only fields written onto a category are silently accepted by the\n  server but make the category unrepairable from the app's UI — which is\n  why `update_category_or_project` type-checks before writing them.\n\n## How this differs from existing alternatives\n\nSeveral good Amazing Marvin MCP servers exist; this one was built fresh\n(no shared code) after studying them, with a different goal — *complete*\ncoverage of the public API rather than a curated subset:\n\n- [bgheneti/Amazing-Marvin-MCP](https://github.com/bgheneti/Amazing-Marvin-MCP)\n  — the established Python server; broad but not complete coverage, no\n  global rate limiting.\n- [Recon2026/marvin-mcp](https://github.com/Recon2026/marvin-mcp) — smaller\n  scope (19 tools), unusually careful research; chose to make reminders\n  read-only over the two-write risk. This server ships reminder writes with\n  explicit warnings instead.\n- [lucasoeth/marvin-mcp](https://github.com/lucasoeth/marvin-mcp) — a\n  different philosophy: a handful of consolidated workflow tools (brief/\n  capture/…) rather than an API mirror, plus direct CouchDB reads for\n  search and completed tasks (which the public API can't do at all). If you\n  want opinionated workflows or search, use theirs; if you want raw,\n  complete API access with the sharp edges documented, use this one.\n- [LucaDeLeo/amazing-marvin-mcp](https://github.com/LucaDeLeo/amazing-marvin-mcp)\n  — a Limited-API subset.\n\n## Credits & sources\n\nNo code was copied from any of these — the build is fresh — but they\nmaterially shaped it:\n\n- **[amazingmarvin/MarvinAPI](https://github.com/amazingmarvin/MarvinAPI)**\n  (+ [wiki](https://github.com/amazingmarvin/MarvinAPI/wiki)) — the official\n  API documentation, OpenAPI spec, data types, and issue tracker this\n  server is built against.\n- **[bgheneti/Amazing-Marvin-MCP](https://github.com/bgheneti/Amazing-Marvin-MCP)**\n  — architecture inspiration, endpoint reference during the initial gap\n  analysis, and the MIT-licensing precedent.\n- **[Recon2026/marvin-mcp](https://github.com/Recon2026/marvin-mcp)** — the\n  reminder two-write integrity risk and the groundwork on recurring-task\n  instances, both verified and documented here.\n- **[lucasoeth/marvin-mcp](https://github.com/lucasoeth/marvin-mcp)** — the\n  `#Category` shortcut bug (reproduced here) and the insight that Marvin's\n  sync database is a real CouchDB usable for reads.\n- **[LucaDeLeo/amazing-marvin-mcp](https://github.com/LucaDeLeo/amazing-marvin-mcp)**\n  — the pointer that `/addTask` parses shortcut syntax server-side (partly\n  confirmed, partly refuted — see the `#Category` finding), and the idea of\n  MCP tool annotations.\n\nBuilt with [Claude Code](https://claude.com/claude-code) (Claude Fable 5).\n\n## License\n\n[MIT](LICENSE).\n",
  "bytes": 21077,
  "sha": "c2ce3e8d240d661a4f2f84f45483c120b979f75f2ea1860a5721406026ee6cc3",
  "repo_slug": "andreasd083/amazing-marvin-complete-mcp",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_io_github_andreasd083_amazing_marvin_com_bc2d8dc8/readme"
}