amazing-marvin-complete-mcp

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.

Tools (37)

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.

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 — 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 (2026-08-19 through 2026-08-29). 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.