MCP server

What is MCP?

kttouk supports the Model Context Protocol (MCP), so AI tools such as Claude Code, Cursor, VS Code, Windsurf and OpenCode can read and change your tasks, notes, projects, tags, captures, reminders and bookmarks.

There are three ways to connect. Most people only need the first.

The easy way: the built-in server

There is nothing to install. While kttouk is open it runs a private server on your computer.

1. Open kttouk and go to Settings → Integrations → Connect AI tools.
2. Pick your AI tool and click Copy. The setup already contains the address (http://127.0.0.1:9090/mcp) and your access key.
3. Paste it into the tool, restart the tool, and ask: "List my inbox tasks."

Your data never leaves your computer. The server only accepts connections from the same computer, kttouk has to stay open, and you can turn the server off in Settings → Integrations (the switch at the top of the page).

Using WSL? WSL cannot reach the Windows 127.0.0.1 by default. Turn on mirrored networking (add networkingMode=mirrored under [wsl2] in C:\Users\<you>\.wslconfig, then run wsl --shutdown), or run the AI tool on Windows.

When kttouk is closed, or a tool must start a program

Use the command-line server, kttouk-mcp. It runs from the kttouk source for now:

pip install -e "apps/mcp-server[sqlite]"
kttouk-mcp --install

--install sets up Claude Desktop, Claude Code, VS Code, Cursor, Windsurf, OpenCode and more in one step. Because kttouk encrypts its database, this server needs the database key — if you cannot provide it, use the built-in server above.

From anywhere: Cloud MCP

Cloud MCP lets a tool reach your kttouk data through a hosted gateway, without kttouk being open. It needs an internet connection, and depending on your plan it may require Pro or Business. You can have up to 3 credentials at a time.

1. Open Settings → Integrations → Cloud MCP and click New credential.
2. Give it a name, choose how long it lasts, and choose what it may do — Off, Read, Edit or Full for tasks, notes, captures, projects and reminders. Start with Read only if you are unsure.
3. Copy the secret (ktt_mcp_…). It is shown once; if you lose it, use Rotate secret to make a new one.
4. Add it to your tool with the address https://mcp.kttouk.com/mcp, for example:

claude mcp add --transport http kttouk https://mcp.kttouk.com/mcp --header "Authorization: Bearer ktt_mcp_YOUR_KEY"

The setup panel in the app fills in the right address for each tool. Revoke a credential (the bin icon) at any time and it stops working on the next request.

Keep it private for now. The permissions you choose are saved with the credential, but the gateway does not enforce them yet. Treat every credential as full access to the workspace you picked.

What it can do

• Create, read, update and delete tasks, notes, captures, projects, tags, reminders and bookmarks, and search across them.
• The built-in server offers 33 tools; the command-line and cloud servers offer 49, adding import/export, calendar providers and AI tools.
• 6 kttouk:// resources and 3 prompts (daily review, inbox zero, project status).

Troubleshooting

• 401 or "invalid key" — copy the access key again from Settings → Integrations.
• Cannot connect — open kttouk and check that the server is on in Settings → Integrations. The status badge in the Connect AI tools card shows whether it is running.
• Works on Windows but not in WSL — see the WSL note above.
• "New credential" is greyed out — sign in, then press Try again in the dialog so your workspace can load.
• Cloud: 402 — your plan does not include Cloud MCP. 429 — more than 120 calls a minute; wait a minute.
• More detail, per-tool setup and fixes are in apps/mcp-server/docs/SETUP.md.