Skip to main content
Glama

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.

Related MCP server: Todoist MCP Server

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

Available Tools

15 tools
get_focusGet Nirvana FocusA

Returns tasks the user has flagged for Focus in Nirvana (seqt > 0), excluding completed or trashed items. These are what the user is actively prioritizing right now.

Inputs: no named parameters.

get_inboxGet Nirvana InboxA

Returns tasks in the Nirvana Inbox (state=0) — unprocessed items the user hasn't categorized yet.

Inputs: no named parameters.

get_laterGet Nirvana LaterA

Returns tasks in Nirvana's Later list (state=5) — things the user will definitely do, but not in the immediate Next queue. Sits between Next and Someday.

Inputs: no named parameters.

get_logbookGet Nirvana LogbookA

Returns completed tasks logged in Nirvana (state=7). Use this to review what the user finished.

Inputs: no named parameters.

get_next_actionsGet Nirvana Next ActionsA

Returns tasks marked as Next Actions in Nirvana (state=1) — concrete, actionable next steps the user has committed to.

Inputs: no named parameters.

get_projectGet Nirvana ProjectA

Returns a single project and all of its direct child items (tasks and sub-projects). Identify the project by its exact id (UUID) or its exact name. Provide exactly one. Use list_projects first to discover names.

Inputs: id, name.

get_recurringGet Nirvana RecurringA

Returns the user's recurring task templates in Nirvana (state=9). These are the rules that spawn task instances on a schedule, not individual occurrences.

Inputs: no named parameters.

get_scheduledGet Nirvana ScheduledA

Returns Scheduled tasks in Nirvana (state=3) — tasks deferred to a specific future start date.

Inputs: no named parameters.

get_somedayGet Nirvana Someday/MaybeA

Returns tasks parked in Nirvana's Someday list (state=4) — things to revisit later but not actionable now.

Inputs: no named parameters.

get_trashGet Nirvana TrashA

Returns tasks the user has thrown into Trash (state=6). These are soft-deleted but recoverable — useful for finding something the user trashed but might want back.

Inputs: no named parameters.

get_waiting_forGet Nirvana Waiting ForA

Returns tasks the user is Waiting on someone else for in Nirvana (state=2). Often blocked on a contact's response or delivery.

Inputs: no named parameters.

list_areasList Nirvana AreasA

Returns the user's Areas in Nirvana — high-level life domains (e.g. 'work', 'personal') that group projects and tasks. Areas are the top-level organizing dimension.

Inputs: no named parameters.

list_projectsList Nirvana ProjectsA

Returns the user's active projects in Nirvana (state=11). Projects are containers that group related tasks under a shared outcome.

Inputs: no named parameters.

list_tagsList Nirvana TagsA

Returns the user's labels in Nirvana — plain tags, GTD contexts (e.g. @phone, @home), and contacts (people the user waits on). Each entry has a kind field distinguishing them. For high-level life domains, use list_areas instead.

Inputs: no named parameters.

search_tasksSearch Nirvana TasksA

Search the user's Nirvana tasks with any combination of filters. At least one filter is required. Trashed and deleted tasks are always excluded. Completed (logged) tasks are excluded unless state: "logged" is passed — pair text search with state="logged" to mine the user's history.

Inputs: text, tag, area, state.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    A4/5.0

    Scored across 15 tools

    Disambiguation5/5

    Each tool targets a specific Nirvana task state or entity (focus, inbox, later, logbook, next actions, project, recurring, scheduled, someday, trash, waiting for, areas, projects, tags, search). The descriptions clearly differentiate overlapping concepts like focus vs. next actions, making selection unambiguous.

    Naming Consistency5/5

    All tool names follow a consistent verb_noun pattern using snake_case: get_*, list_*, search_*. No mixing of conventions or vague verbs. The naming is predictable and discoverable.

    Tool Count4/5

    With 15 tools, the count is at the upper boundary of the ideal range. It covers many task states and organizational entities, which is reasonable for a full-featured GTD app. Slightly high but still well-scoped.

    Completeness2/5

    The tool set covers all retrieval needs for task states, projects, areas, and tags, but completely lacks mutation tools (create, update, delete for tasks or projects). This is a significant gap, as agents cannot modify the user's task system, limiting practical usage.

    Maintenance

    ActivityInactive
    ResponsivenessOutdated data

    Related MCP Connectors

    Related MCP Servers