amazing-marvin-complete-mcp

# amazing-marvin-complete-mcp

<!-- mcp-name: io.github.andreasd083/amazing-marvin-complete-mcp -->

An MCP ([Model Context Protocol](https://modelcontextprotocol.io)) server for
[Amazing Marvin](https://amazingmarvin.com) with **complete coverage of the
public API**: 34 tools over all ~31 documented endpoints, a global rate
limiter that respects Marvin's documented limits, least-privilege token
routing, and MCP tool annotations. 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](#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 (34)

| 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_children`, `get_categories` |
| Structure | `create_category_or_project` |
| 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](https://modelcontextprotocol.io/specification/2025-06-18/server/tools#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](https://app.amazingmarvin.com/pre?api)):

- **API Token** (`MARVIN_API_TOKEN`, required) — limited access; enough for
  reading and creating tasks.
- **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](SECURITY.md).

## Install & run

Requires Python 3.12+.

**From PyPI** (recommended): with [uv](https://docs.astral.sh/uv/) installed
there is nothing to set up — point your MCP client at
`uvx amazing-marvin-complete-mcp` as shown below.

**From source:**

```bash
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:

```json
{
  "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)

```bash
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](.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 on 2026-08-19. 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](https://github.com/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](https://github.com/amazingmarvin/MarvinAPI/issues/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/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.

**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 `/unclaim