amazing-marvin-mcp

Overview

An unofficial MCP server for Amazing Marvin, so an assistant such as Claude can answer "what's in my inbox?", "what's due this week?", "I'm at the car, what can I do?", and act on it: rename, relabel, reschedule, move, split into projects, save research into a note.

This project is not affiliated with, endorsed by, or supported by Amazing Marvin; it uses their public API.

How it works

Claude ──MCP (stdio)──▶ amazing-marvin-mcp
                          ├─ local mirror ◀── CouchDB `_changes` (your sync database)
                          │    reads, search and filters run here: no rate-limit cost
                          └─ writes ──▶ Marvin REST API (addTask, doc/update, markDone)
                                        throttled to Marvin's limits (1 request / 3 s)

Marvin's REST API has no "list" or "search" endpoint and a budget of 1440 requests per day, so reads come from a local copy of your database kept fresh with an incremental _changes poll (at most once a minute). Writes go through the REST API, which handles Marvin's conflict-resolution bookkeeping (fieldUpdates) server-side.

What the assistant knows

• Marvin semantics, in the UI's own words. Inbox = not filed anywhere; categories and projects nest arbitrarily (the Master List). The four dates are kept apart: Do date (the day you plan to do it, "scheduled"), Due date (hard external deadline), End date (self-imposed target; Planning Ahead's planned week/month is the softer form), Start date (hidden on the Backburner until then). Plus Duration estimates (minutes), Importance (P1–P3 stars), Eat-the-Frog, Backburner, labels and label groups.

• Your structure (get_structure): the category/project tree with ids and open-task counts, labels by group, and which Marvin strategies you have enabled (by their names in the Strategies screen).

• Your workflow (workflow.md or a workflow/ directory of sections): how you use Marvin: what labels mean, how you plan, your inbox-triage checklist, what "short win" means. Marvin is flexible, so this is what lets the assistant act the way you would. It is injected into the server instructions and exposed as marvin://workflow (and marvin://workflow/<section>).

Tools

There is deliberately no delete tool: Marvin's trash is client-side, so API deletes are unrecoverable.

Related MCP server: Amazing Marvin MCP

Install and set up (using it)

1. Install (needs uv):

   uv tool install git+https://github.com/tsvikas/amazing-marvin-mcp.git

2. Credentials. In Marvin, enable the API strategy (Strategies → API → settings). Put its values in ~/.config/amazing-marvin-mcp/.env (Linux; amazing-marvin-mcp check prints the exact path on your OS):

   MARVIN_API_TOKEN=...           # create / mark done
   MARVIN_FULL_ACCESS_TOKEN=...   # edit existing items; omit for no edits
   MARVIN_SYNC_SERVER=...         # CouchDB: the read mirror
   MARVIN_SYNC_DATABASE=...
   MARVIN_SYNC_USER=...
   MARVIN_SYNC_PASSWORD=...

   Environment variables and a .env in the working directory also work (and override the per-user file). While trying things out, use a second, throwaway Marvin account: the full-access token can damage data.

3. Check and first sync:

   amazing-marvin-mcp check     # verifies tokens, pulls the database, prints counts

4. Describe your workflow:

   amazing-marvin-mcp init-workflow            # one workflow.md to edit, or
   amazing-marvin-mcp init-workflow --split    # a workflow/ directory: planning, labels, triage, daily…

   Everything in it goes into the model's instructions (and each section is also a marvin://workflow/<section> resource), so keep it short and concrete.

5. Register with your MCP client.

   Claude Code:

   claude mcp add marvin -- amazing-marvin-mcp serve

   Claude Desktop (claude_desktop_config.json):

   {
     "mcpServers": {
       "marvin": { "command": "amazing-marvin-mcp", "args": ["serve"] }
     }
   }

   Both read the per-user .env, so no secrets go in the client config. Then ask: "what's in my Marvin inbox?"

Other settings (shown by check): MARVIN_WORKFLOW_FILE (file or directory), MARVIN_CACHE_DIR, MARVIN_MIN_REQUEST_INTERVAL (seconds between REST calls, default 3), MARVIN_MIRROR_MAX_AGE (seconds before a read re-polls, default 60).

The mirror file holds all your tasks; it is written with owner-only permissions under the cache directory.

Developing

git clone https://github.com/tsvikas/amazing-marvin-mcp && cd amazing-marvin-mcp
uv sync && just prepare                     # deps + pre-commit hooks
just test && just lint

Run the server from the checkout (a .env in the repo root is git-ignored and is picked up when the client starts from this directory; otherwise use -e VAR=value or the per-user file):

claude mcp add marvin-dev -- uv run --directory "$PWD" amazing-marvin-mcp serve

tests/test_live.py runs every tool end to end and replays a recorded cassette by default (tests/cassettes/), which doubles as a fixture of real Marvin documents. To re-record against a throwaway account (it creates and then deletes a few [live] items):

MARVIN_API_TOKEN=... MARVIN_FULL_ACCESS_TOKEN=... MARVIN_SYNC_SERVER=... \
MARVIN_SYNC_DATABASE=... MARVIN_SYNC_USER=... MARVIN_SYNC_PASSWORD=... \
uv run pytest tests/test_live.py --record-mode=rewrite

Design rules for contributions are in CLAUDE.md.

Contributing

Interested in contributing? See CONTRIBUTING.md for development setup and guidelines.