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

Tool	What it does
get_structure	Category/project tree with ids, labels by group, strategies in use
list_inbox	Open inbox tasks, oldest first
list_today [day]	Do date that day, do date earlier but not done, due by then
list_due [by]	Open tasks with a due date by a date (week, month, YYYY-MM-DD)
search_tasks …	Any mix of text, parent, labels, do-date window, due/end by, estimate, flags
get_task id	Full detail of a task (note, subtasks, dates) or a project (its open children)
list_children parent	Direct tasks and sub-projects of a project/category
create_task / create_project	Names for parent/labels are resolved for you
create_category / create_label	New folder in the Master List; new label (in an existing or new group)
update_subtasks id …	Add, complete, reopen, rename, remove subtasks
update_task id …	Rename, move, relabel, do/due/end/start date, estimate, note, importance, clear…
mark_done id	Complete a task/project
sync_marvin	Force a mirror refresh
Prompts: triage_inbox, daily_review	Built from your workflow file

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

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.