Connect Nirvana to external AI clients via MCP
Nirvana ships a native Model Context Protocol (MCP) server. Connect it to an external AI client — Claude, ChatGPT, Cursor, VS Code, Claude Code, Gemini CLI, or any MCP-compatible app — and that client can read and write your tasks and projects directly, without the Nirvana app running.
This is separate from Nirvana's built-in AI assistant, which lives inside the Nirvana app. MCP is for connecting external AI clients to your account.
What the AI client can access
Once connected, the client can:
- Read your tasks — by GTD state (Inbox, Next, Waiting, Scheduled, Someday, Later, Focus), by project, by tag, or by date range
- Read task counts — totals per GTD list
- Read your tags — contexts and areas with usage counts
- Create tasks and projects — with name, notes, state, tags, due date, scheduled start date, energy, and time estimate
- Update tasks (requires Nirvana Pro) — change any field, complete, star/unstar, move between lists, or soft-delete to trash
The client can only access your data. It cannot see any other user's account, and it never sees your Nirvana password.
How to connect
Setup guides for every supported client live at nirvanahq.com/mcp — no sign-in needed. Pick your app there and follow its steps. The connection itself happens inside the AI app: it opens Nirvana's sign-in screen, you approve access, and the app appears under Connected Apps on your MCP dashboard.
| Client | Install path |
|---|---|
| Claude (claude.ai) | One-click Open in Claude — launches the Add custom connector dialog |
| ChatGPT | One-click Open in ChatGPT — lands on Settings → Connectors → Advanced |
| Claude Code | Copyable claude mcp add CLI command |
| Cursor | One-click Add to Cursor deeplink |
| VS Code | One-click Add to VS Code with the server pre-filled |
| Gemini CLI | Copyable gemini mcp add CLI command (the Gemini app itself doesn't support connectors yet) |
| Other clients | Copyable mcpServers.json snippet (Continue, Zed, and any client that reads that format) |
The setup guides at nirvanahq.com/mcp are the source of truth for install steps — they stay up-to-date as connectors evolve. The Nirvana MCP server URL is always https://mcp.nirvanahq.com/mcp.
Plan requirements
On the Nirvana side: Free accounts get full read access plus task and project creation. Updating existing tasks (renaming, retagging, completing, starring, moving between lists) requires Nirvana Pro.
On the client side: Most MCP clients (Claude, Cursor, Claude Code, VS Code, Gemini CLI) work on their free or paid tiers. ChatGPT requires a paid plan — Developer Mode is available on Plus, Pro, Business, Enterprise, and Edu accounts, with full read and write access (ChatGPT asks you to confirm each write action; on Business and up, a workspace admin can restrict it). Free and Team plans don't have Developer Mode at this time, and the flow is web-only — there's no MCP support in the ChatGPT mobile app yet.
Security model
Every supported client authenticates through Nirvana's sign-in screen and receives a short-lived access token plus a refresh token — no password or long-lived secret is ever pasted into the AI client.
All requests are scoped to your single Nirvana account. The MCP server cannot read or write to anyone else's data.
Manage and revoke access
The MCP dashboard lists every app connected to your account under Connected Apps. Disconnect any of them at any time — access ends immediately.
If you suspect a session is compromised, disconnect it from the dashboard and reconnect the affected client.
For developers
Building your own agent or script? mcp.nirvanahq.com/developers has personal access tokens (long-lived keys for clients without OAuth) and an interactive playground where you can run every MCP tool against your own account, plus a recommended system prompt for GTD-aware agent behaviour.
Troubleshooting
"No tools available" or zero actions shown after connecting. The access token most likely expired and the client didn't refresh cleanly. Disconnect from the dashboard, then reconnect from the client.
Create or update actions fail with "requires a Pro subscription".
update_tasks requires Nirvana Pro. create_tasks works on Free.
ChatGPT shows tasks but won't create or update them. ChatGPT asks for confirmation before every write action — check the conversation for a pending approval. In Business, Enterprise, and Edu workspaces, an admin may also have restricted write actions or the connector itself.
Connector worked yesterday, broke today. Disconnect and reconnect from the dashboard. OAuth refresh tokens sometimes drop after long idle periods, and the cleanest fix is a fresh handshake.