IkunaHow to Connect an AI Client to Ikuna over MCP
The Model Context Protocol (MCP) lets an AI client read your local Ikuna focus data and act on your workspaces. Here is how to connect Claude Desktop or Codex, the permission and privacy controls, and which clients work today.
Ikuna already holds a clear record of your workday: what you worked on, where your time went, and how often you switched context. AI Connections let an AI client read that record and answer questions about it, and act on your saved workspaces, without sending your workday somewhere else.
The connection uses the Model Context Protocol, an open standard for linking AI clients to local tools and data. Ikuna runs a built-in MCP helper on your Mac, and a supported client talks to it on terms you set. Here is the method, step by step.
Which clients work today
Two clients have one-click setup. Any other client that speaks MCP can connect through manual setup. One common tool cannot connect at all, and it helps to know why up front.
| Client | Status | Notes |
|---|---|---|
| Claude Desktop | Supported | One-click setup from Ikuna Settings. |
| Codex | Supported | One-click setup from Ikuna Settings. |
| Other MCP clients | Manual setup | Point the client at the same local Ikuna MCP server by hand. |
| Ollama | Not supported | A model runtime, not an MCP client. It cannot open an Ikuna connection. |
Ollama is the common point of confusion. Ollama runs local models, but it is a model runtime, not an MCP client. It does not act as a Model Context Protocol host, so it cannot open an Ikuna connection. To use a local model with Ikuna, run it inside an MCP client such as Claude Desktop instead.
Open AI Connections in Settings
AI Connections live in Ikuna Settings. The connection is opt-in, so nothing is shared until you turn it on. From this screen Ikuna can add its own MCP connection to a supported client for you, or you can copy the details and configure a client by hand.
Update to Ikuna 1.2.4 or later, then open Settings and find the AI Connections section.
Add the connection to your client
For Claude Desktop and Codex, Ikuna sets up the connection in one click. It backs up the client configuration first, adds its own MCP connection, and keeps the other MCP servers you already use. It never replaces an existing Ikuna connection that points somewhere else. For any other MCP client, point it at the same local Ikuna MCP server by hand.
Pick Claude Desktop or Codex for one-click setup. Use manual setup for other MCP clients.
Set what each capability can do
Each capability has three states: Always allow, Needs approval, or Blocked. Read capabilities cover today's activity summary, activity timelines and focus blocks, historical reports and period comparisons, saved workspaces, and the active workspace. Action capabilities let a client start, stop, save, create, or edit an Ikuna, open the Dashboard, and, for Pro users, control Focus Shield.
Start with Needs approval for actions, so you confirm each change before it happens.
Ask your first question
With the connection live, ask the client about your workday. Try "What did I actually work on today?", "Where did my time go this week?", "What were my biggest context switches?", or "Give me a standup from my workday." The client reads your local Ikuna context to answer.
Keep it read-only at first. Confirm the answers match your day before you grant action capabilities.
Permission and privacy controls
AI Connections are opt-in, and you stay in control of what a client can see and do. The controls sit in Settings, next to the connection itself.
- Per-capability permission: set each capability to Always allow, Needs approval, or Blocked.
- Choose what context is shared: hide web addresses entirely, share domains only without full paths or query parameters, or share full URLs when you want that context available.
- Hide window titles: window titles can hold project, document, or file names, so you can keep them out of what a client sees.
- Local access audit: a local log shows when a connected client used an Ikuna capability.
Doing it with Ikuna
AI Connections ship in Ikuna 1.2.4 and later. The MCP helper is built in and runs locally, so your workday stays on your Mac.
- One-click setup: connect Claude Desktop or Codex from Settings, with your other MCP servers left in place.
- Read your focus data: ask about today's work, where your time went, and your biggest context switches.
- Act on your workspaces: start, stop, save, or edit an Ikuna, open the Dashboard, and control Focus Shield on Pro.
- Opt-in and local: the connection is off until you turn it on, and the helper runs on your Mac.
Native macOS · Local data · Built in EU
Common questions
Which AI clients can connect to Ikuna over MCP?
Claude Desktop and Codex have one-click setup from Settings. Any other client that speaks the Model Context Protocol can connect to the same local Ikuna MCP server through manual configuration.
Can I connect Ollama to Ikuna over MCP?
No. Ollama is a model runtime, not an MCP client. It runs local models but does not act as a Model Context Protocol host, so it cannot open an Ikuna connection. Use an MCP client such as Claude Desktop or Codex instead.
Does connecting an AI client send my workday to the cloud?
No. The Ikuna MCP helper runs locally on your Mac. A connected client reads your own local Ikuna context on terms you set. The connection is opt-in, and every capability can be set to Always allow, Needs approval, or Blocked.
Will connecting Ikuna overwrite my other MCP servers?
No. Ikuna backs up the client configuration first, adds its own connection, and keeps the other MCP servers you already use. It never replaces an existing Ikuna connection that points somewhere else.