nirvana-mcp

MCP server that exposes NirvanaHQ — the GTD task manager — to Claude Code and other MCP-compatible clients.

Status: 17 read-only tools shipped (see docs/tools.html for the full reference). Writes are next. See PLAN.md for the roadmap.

Install into Claude Code

Prerequisites: Node.js 20 or newer (ships with npx) and the Claude Code CLI. Nothing needs to be cloned or globally installed — npx -y downloads the package on demand.

# 1. Get a Nirvana auth token. Prompts for username + password.
npx -y @sgoettschkes/nirvana-mcp login

# 2. Install the server. Paste the token from step 1.
claude mcp add nirvana \
  --env NIRVANA_AUTH_TOKEN=<paste-token-here> \
  -- npx -y @sgoettschkes/nirvana-mcp

# 3. Restart Claude Code, then ask: "What's in my Nirvana inbox?"

To remove: claude mcp remove nirvana.

Tools

| Tool | Description | |---|---| | list_inbox | Tasks in the Inbox (state=0) — unprocessed items not yet categorized. | | list_next_actions | Tasks marked Next (state=1) — concrete, actionable next steps. | | list_waiting_for | Tasks Waiting on someone else (state=2). | | list_scheduled | Tasks deferred to a future start date (state=3). | | list_someday | Tasks parked in Someday/Maybe (state=4). | | list_later | Tasks in the Later list (state=5) — between Next and Someday. | | list_trash | Soft-deleted tasks (state=6), still recoverable. | | list_logbook | Completed tasks (state=7) — currently returns all-time history. | | list_recurring | Recurring task templates (state=9) — the rules, not individual occurrences. | | list_focus | Tasks flagged for Focus (seqt > 0), excluding completed/trashed items. | | list_projects | Active projects (type=1, state=11). | | get_project | One project plus its direct children (tasks and sub-projects). Identify by id or name. | | list_areas | High-level life domains (e.g. "work", "personal"). | | list_tags | Plain tags + contacts (with a kind field). In current Nirvana, GTD contexts are stored as plain tags. | | list_reference_lists | Reference Lists (type=3, state=10) — top-level containers for non-actionable notes / lookup material. | | get_reference_list | One Reference List plus all its items. Identify by id or name. | | search_tasks | Filter tasks by text (name+note substring), tag, area, and/or state. At least one filter required. |

How it works

NirvanaHQ has an undocumented HTTP API at https://api.nirvanahq.com. This server:

1. Calls auth.new with your username and the MD5 of your password to obtain a long-lived auth token.
2. Calls the bulk everything endpoint and filters the result client-side to answer each tool.

Your password is hashed locally and never stored. Only the auth token is persisted (in your MCP client's config). Revoke it any time by changing your Nirvana password.

Troubleshooting

• Nirvana API error 98: Invalid Login Details — wrong username/password.
• Missing required env var: NIRVANA_AUTH_TOKEN — run nirvana-mcp login first and put the token in your claude mcp add command.
• Nirvana API error from a tool call — your token was probably revoked (changing your Nirvana password does this). Re-run nirvana-mcp login, then claude mcp remove nirvana && claude mcp add ... with the new token.

Development

git clone https://github.com/Sgoettschkes/nirvana_mcp
cd nirvana_mcp
asdf install                # installs the pinned Node version
npm install
cp .env.example .env        # creates .env with an empty NIRVANA_AUTH_TOKEN

npm run login               # prompts for username + password,
                            # prints an auth token. Paste it as
                            # NIRVANA_AUTH_TOKEN in .env.

npm run dev                 # runs the server against your account
npm run inspect             # builds, then opens MCP Inspector

When verifying the published install from inside this repo, the package.json name collides with the npm package, and npx -y @sgoettschkes/nirvana-mcp … will fail with command not found. Run from a different directory (cd ~ && npx …) or use the explicit form: npx -y --package=@sgoettschkes/nirvana-mcp nirvana-mcp ….

License

MIT