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**: 50 tools over the 38 endpoints on Marvin's
[API endpoints page](https://help.amazingmarvin.com/amazing-marvin/api-endpoints)
(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](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](#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)

| Group | Tools |
|---|---|
| Core | `test_connection`, `create_task`, `mark_done`, `mark_project_done`, `unmark_done`, `update_task`, `set_priority`, `delete_task` |
| Reading | `get_today_items`, `get_due_items`, `get_done_items`, `get_children`, `get_categories` |
| Recurring tasks | `create_recurring_task`, `update_recurring_task` |
| Notebooks | `get_notebooks`, `get_notebook`, `search_notebooks`, `create_notebook`, `update_notebook`, `delete_notebook`, `create_notebook_page`, `update_notebook_page`, `delete_notebook_page` |
| 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`, `list_capabilities` |

### 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.

| Area | Can via MCP | Cannot via MCP (done in the app) |
|---|---|---|
| Tasks | create/update/complete/delete, priority and frog 1–4, size, subtasks, a time of day and own reminders in the app's form, day, deadline, labels, estimate, note, sections, planned week/month, review date, backburner, orbit, snooze, time block; complete a project with its open tasks (two steps); read today's, due and done, filtered as the app shows them | startDate at creation (update_task afterwards); fixing occurrences that already exist; reopening a completed project |
| Recurring tasks | create all eleven types (custom only as an RRULE string), change rule/window/place/properties, clean up occurrences that no longer fit (list, confirm) | reminders/frog on recurring tasks, recurring projects, custom rules in words |
| Notebooks | list, read, search, create, rename, sections, pages: create/edit/move/delete, delete a notebook in two steps | undo (no trash via the API) |
| Structure | the hierarchy, children, create/update/convert categories and projects, labels on both, color, icon, note; read labels and goals | creating/editing labels, goals, smart lists, strategies |
| Habits | list, tracking record, record/undo; habit tasks are recorded on mark_done and undone on unmark_done | creating/editing habits |
| Time | today's time blocks with mapping, create a block, time tracking start/stop/history | the smart-time-block mapping on a block |
| Rewards | kudos, award/undo/spend/reset reward points | undoing a MANUAL award; reading the app's Rewards |
| Reminders | own reminders on a task (list + server entry), standalone, delete; time of day via update_task | — |
| Calendar | create an event (experimental) | reading/editing events |
| Account | test, account info, call budget, capability overview | — |

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](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 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](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 — 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