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, 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
Open the Nirvana MCP dashboard and pick the client you want to connect. Each card opens a short install guide tailored to that client:
| 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 |
| Cursor | One-click Add to Cursor deeplink |
| Claude Code | Copyable claude mcp add CLI command |
| VS Code | One-click Add to VS Code with the server pre-filled |
| Other clients | Copyable mcpServers.json snippet (Continue, Zed, and any client that reads that format) |
The dashboard is the source of truth for install steps — it stays 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) work on their free or paid tiers. ChatGPT is the exception — MCP connectors live in Developer Mode, which is available on:
- Pro — read-only (ChatGPT blocks write actions like
create_tasksandupdate_taskson this tier regardless of your Nirvana plan) - Business, Enterprise, Edu — full access, including write actions
ChatGPT Free, Plus, and Team plans do not have Developer Mode at this time. The flow is also 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
Visit the Nirvana MCP dashboard to see every client connected to your account. Disconnect any client to revoke its access immediately.
If you suspect a session is compromised, disconnect it from the dashboard and reconnect the affected client.
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. If you're on ChatGPT Pro, any write action is blocked by ChatGPT regardless of your Nirvana plan — upgrade to ChatGPT Business+ or use a different client.
ChatGPT shows tasks but won't create or update them. You're on ChatGPT Pro. Developer Mode on Pro is read-only. Switch to Business, Enterprise, or Edu, or use one of the other clients above for full read+write.
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.