nirvana-mcp
The nirvana-mcp server provides read-only access to your NirvanaHQ GTD task manager via 17 tools, exposing the following capabilities:
Task List Retrieval
Inbox (
get_inbox) — Unprocessed, uncategorized tasksNext Actions (
get_next_actions) — Concrete, actionable next stepsWaiting For (
get_waiting_for) — Tasks blocked on someone elseScheduled (
get_scheduled) — Tasks deferred to a future dateSomeday/Maybe (
get_someday) — Tasks parked for later considerationLater (
get_later) — Tasks between Next and SomedayTrash (
get_trash) — Soft-deleted, recoverable tasksLogbook (
get_logbook) — Completed tasksRecurring (
get_recurring) — Recurring task templates/rulesFocus (
get_focus) — High-priority flagged tasks
Projects & Organization
List Projects (
list_projects) — All active projectsGet Project (
get_project) — A specific project (by name or ID) with its child tasks and sub-projectsList Areas (
list_areas) — High-level life domains (e.g. work, personal)List Tags (
list_tags) — All tags, GTD contexts (@home, @phone), and contacts
Search & Filtering
Search Tasks (
search_tasks) — Filter tasks by any combination of free-text (name/note), tag, area, and state (inbox, next, waiting, scheduled, someday, later, logged, recurring, active_project)
No write operations are supported — the server is currently read-only; creating, modifying, or deleting data is not implemented.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@nirvana-mcp What's in my inbox?"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
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 |
| Tasks in the Inbox (state=0) — unprocessed items not yet categorized. |
| Tasks marked Next (state=1) — concrete, actionable next steps. |
| Tasks Waiting on someone else (state=2). |
| Tasks deferred to a future start date (state=3). |
| Tasks parked in Someday/Maybe (state=4). |
| Tasks in the Later list (state=5) — between Next and Someday. |
| Soft-deleted tasks (state=6), still recoverable. |
| Completed tasks (state=7) — currently returns all-time history. |
| Recurring task templates (state=9) — the rules, not individual occurrences. |
| Tasks flagged for Focus ( |
| Active projects ( |
| One project plus its direct children (tasks and sub-projects). Identify by |
| High-level life domains (e.g. "work", "personal"). |
| Plain tags + contacts (with a |
| Reference Lists ( |
| One Reference List plus all its items. Identify by |
| Filter tasks by |
How it works
NirvanaHQ has an undocumented HTTP API at https://api.nirvanahq.com. This server:
Calls
auth.newwith your username and the MD5 of your password to obtain a long-lived auth token.Calls the bulk
everythingendpoint 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— runnirvana-mcp loginfirst and put the token in yourclaude mcp addcommand.Nirvana API errorfrom a tool call — your token was probably revoked (changing your Nirvana password does this). Re-runnirvana-mcp login, thenclaude 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 InspectorWhen 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 toolsget_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
Scored across 15 tools
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.
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.
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.
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
Related MCP Connectors
Nifty's MCP server — exposes tasks, projects, messages, and files as tools for AI agents.
MCP server for generating rough-draft project plans from natural-language prompts.
Shared memory MCP server for Claude Code, Codex, Gemini CLI and Cursor. Cited, editable.
Official Todoist MCP server. Manage tasks and projects. Hosted, no API key needed.
Related MCP Servers
- AlicenseAqualityCmaintenanceMCP Server for the Notion API, enabling Claude to interact with Notion workspaces.313,089 npm925MIT
- AlicenseAqualityDmaintenanceAn MCP server that integrates Claude with Todoist, enabling natural language task management including creating, updating, completing, and deleting tasks.5281 npm392MIT
- AlicenseBqualityDmaintenanceAn MCP server that connects Claude with Todoist for complete task and project management through natural language.86203 npm246MIT
- AlicenseNot gradedqualityDmaintenanceAn OAuth-authenticated MCP server that bridges Claude AI with a task management system, allowing users to list, create, and update tasks through natural language commands.1ISC