Marvin Mcp

marvin

Use Amazing Marvin from your terminal, and let AI assistants like Claude read and update your tasks.

Two things you can do with it:

Talk to your task list. Connect it to Claude and say "what should I focus on today?", "move everything I didn't finish to tomorrow", or "add the six things from this email as tasks in my Work project". Claude reads your real Marvin tasks and makes the changes in your real account.

Type instead of click. marvin shows today. marvin capture "call the dentist +tomorrow" adds a task. No app switching, no waiting for a page to load.

It's free, open source, and works with your existing Amazing Marvin account.

---

What it looks like

$ marvin

2026-07-26

Today (3)
  - Write the migration plan  (frog, 90m)  [a4f2...]
  - Review PR #412  (!!, 30m)  [8c1e...]
  - Book flights  (due 2026-07-28)  [3b90...]
  2h30m estimated

Due soon, no day assigned (1)
  - Renew passport  (due 2026-07-29)  [d55a...]

That last section is the whole reason this exists. A task with a deadline and no day assigned is how things quietly go overdue — Marvin knows about it, but it isn't on any day's list, so you never see it until it's late. This puts it in front of you while there's still time.

---

Setup

Two ways in. Both need the same six values from Marvin, and you only do this once.

Just Claude Desktop? No terminal needed.

1. Download marvin-.mcpb from the

latest release.

1. Double-click it. Claude Desktop opens and asks whether to install.
2. Paste the six values from step 2 below into the form it shows you.

That's the whole thing. You don't need Node.js, npm or anything else installed — Claude Desktop brings its own, and everything the server needs is inside the file. Desktop stores the credentials in your operating system's keychain.

Skip to [step 2](#2-get-your-amazing-marvin-tokens) for where the six values live, then to [Everyday use](#everyday-use).

Want the command line too?

Then it's three commands and about two minutes.

1. Install it

npm install -g marvin-mcp

If that fails with "command not found: npm", you need Node.js first — download the LTS version, install it, then run the command again.

2. Get your Amazing Marvin tokens

Everything you need is on one page: Settings → API.

At the top, two buttons generate tokens:

• API Token
• Full Access Token

Further down the same page, under the sync database section, four more values:

• Sync server, database, user, password

These are passwords for your account — don't paste them into a public chat or a GitHub issue.

3. Save them

marvin auth \
  --api-token PASTE_API_TOKEN \
  --full-access-token PASTE_FULL_ACCESS_TOKEN \
  --sync-server PASTE_SERVER \
  --sync-database PASTE_DATABASE \
  --sync-user PASTE_USER \
  --sync-password PASTE_PASSWORD

It checks the tokens with Marvin before saving anything, so if a paste went wrong you'll find out immediately rather than three commands later. The tokens end in =, which is the character people most often miss when selecting by hand.

That's it. Run marvin and you should see today.

Why six values and not two?

Marvin's public API has no search endpoint and can't return completed tasks at all, so without the sync database, search meant walking your entire project tree — about 22 requests per search against an allowance of 1440 a day, and it still couldn't see anything you'd finished.

Marvin enforces that allowance by restricting accounts rather than by returning an error, so the failure mode was your account getting flagged. That's not something to ship to somebody else as a default. With the sync credentials, search is a single query, it's roughly 20× faster, and it sees your completed history.

Reads use the sync database. Every write still goes through the official API, because that's what handles conflict resolution when you're also editing on your phone.

Your tokens are saved to ~/.marvin/config.json, readable only by you. You won't need to enter them again, and marvin will work from any folder.

---

Everyday use

marvin                                    # what's today
marvin capture "call the dentist"         # add a task
marvin capture "file taxes +tomorrow"     # ...for tomorrow
marvin complete "dentist"                 # tick it off
marvin tasks "invoice"                    # search everything
marvin tasks --parent inbox               # your inbox
marvin tasks --unscheduled                # captured, never given a day
marvin hierarchy                          # your projects and categories
marvin apply --changes '[...]'            # a batch of changes in one go

marvin complete accepts part of a title, so you don't have to look anything up. If the fragment matches more than one task it stops and shows you the options rather than guessing.

Deadlines vs. days

Marvin has two date fields, and mixing them up is the single easiest way to make a mess. This tool renames them so you can't:

• --scheduled-for — the day you plan to work on it
• --due-by — the actual deadline

marvin capture "file taxes" --due-by 2026-09-01 --scheduled-for 2026-08-20

Plan to start on August 20th. Hard deadline September 1st. Two different things.

Changes are immediate

There's no undo. A write goes straight to Marvin, and Marvin has no undo either, so a deletion in particular is permanent — recreating a task gives it a new id. Prefer completing or rescheduling a task over deleting it.

Prefer one apply over a sequence of single writes: it is one ordered set, applied in order, and one round trip instead of twelve against an account with a daily request allowance.

Add --json to any command if you want to pipe the output into something else.

---

Connecting Claude

This is the part that makes it more than a keyboard shortcut.

Claude Code:

claude mcp add marvin -- marvin-mcp

Claude Desktop — if you installed the .mcpb, you're already done; it's under Settings → Extensions. Otherwise open Settings → Developer → Edit Config and add:

{
  "mcpServers": {
    "marvin": {
      "command": "marvin-mcp"
    }
  }
}

Restart Claude. No tokens in the config file — it reads the ones you already saved in step 3.

Then just talk to it:

> "What's on my plate today? Anything I should move?" > > "I'm out sick. Push everything from today to Thursday." > > "Here are my notes from the meeting — pull out the action items and add them > to my Work project with deadlines."

Claude can read and change your tasks, so treat it the way you'd treat an assistant with access to your calendar. Every tool that writes is marked as destructive in the protocol, so a well-behaved MCP client shows you the call and waits for your approval before it runs — that approval is the check, because there's no undo afterwards.

Other MCP clients, and remote access from your phone

Any MCP client works — the server is a standard stdio MCP server, run as marvin-mcp.

For remote access (Poke, or anything that can't run a local process), there's an HTTP server:

API_KEY=some-long-random-string npm run mcp:remote

It refuses to start without API_KEY, because it's internet-reachable and has write access to your tasks. Generate a real random string for it and don't reuse a password.

Clients authenticate with Authorization: Bearer . A ?token= query parameter also works, for hosted clients that can't set headers, but prefer the header where you have the choice: keys in URLs end up in access logs, proxy logs and Referer headers, and you can't un-leak a key once a log has shipped somewhere.

---

Your data

Worth being explicit, since this asks for tokens to your task list:

• It runs entirely on your own machine. There is no server of mine involved.
• It talks to exactly two places, both Amazing Marvin's: their API for writes,

and their sync database for reads. Nothing else, ever.

• Your tokens are stored in ~/.marvin/config.json with permissions that make

the file readable only by your user account. They're never transmitted anywhere except to Amazing Marvin.

• No telemetry, no analytics, no crash reporting, no phoning home. Nothing about

you or your tasks is ever sent to me.

If you connect it to Claude, then Claude sees whatever tasks it reads — that's the point of connecting it, but it's worth saying out loud.

---

What it deliberately doesn't do

Marvin has around seventy fields on a task. This exposes nine: title, notes, scheduled day, deadline, time estimate, project, priority, frog, and labels.

No habits, goals, trackers, rewards, time tracking, recurring tasks, subtasks, dependencies, snoozing, or time blocks. That's not an oversight and it's not a roadmap — a small surface is why the tool is predictable enough to hand to an AI. If you need Marvin's full power, use Marvin. This is for the daily loop.

---

Contributing

Bug reports and pull requests welcome.

npm install
npm test
npm run typecheck

Adding a capability means adding one file in src/core/ops/. The CLI command and the MCP tool are both generated from it, so the two surfaces can't drift apart. AGENTS.md has the architecture and a list of Marvin API quirks that were all found the hard way — read that before changing anything that talks to the API.

MIT licensed. Not affiliated with Amazing Marvin LLC.

Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: lucasoeth
• Source: lucasoeth/marvin-mcp
• License: MIT
• Homepage: https://github.com/lucasoeth/marvin-mcp#readme

Install and usage instructions live in the source repository linked above.