Guide · AI Connections

Connect Claude, Codex or another AI client to Ikuna

Your AI can use the focus and workspace capabilities you explicitly allow, through a local server on your Mac. Ikuna does not send your prompts or activity history to a cloud service on its own.

One-line MCP install

npx -y ikuna-mcp

The npm bridge connects your MCP host to the signed helper included with Ikuna.

Ikuna 1.2.6 · macOS · Node.js 18 or later

What the connection enables

Ask for an evidence-backed review of your day or week. Inspect switching patterns, active time and deep-work blocks within the access you grant. With workspace control enabled, your client can also start or restore an Ikuna from the conversation.

Ikuna remains the source of the work data. If there is too little history for a useful answer, the result should say "not enough evidence" instead of inventing a productivity story.

Before you connect

Install Ikuna 1.2.6 or later and leave the app running.
Install Node.js 18 or later so npx is available.
Open Settings → AI Connections in Ikuna and choose the capabilities you want to share.
Use an MCP-capable host. Guided setup detects Claude Desktop, Codex, Claude Code and Cursor.

Choose access in Ikuna

Open Settings → AI Connections. Activity reads, sensitive context such as window titles and URLs, and workspace control are separate permissions. Grant only what this client needs.

Run guided setup

In Terminal, run:

npx -y ikuna-mcp setup

Setup detects supported clients, adds only Ikuna's entry to their existing configuration, keeps backups and checks the local MCP bridge. To repair stale values later, run npx -y ikuna-mcp setup --repair.

Restart, then make a real request

Restart or reconnect the client if it was already open. Then ask a normal Ikuna-related question, such as "What did I work on today?" A real tool request from that named client is what makes the connection Live verified in Ikuna.

Connection status, without guesswork

Status	What it means	What to do
Setup saved	Ikuna found its own configuration entry.	Restart the client if needed.
Client detected	The client is installed and its configuration can be read.	Make a real Ikuna request.
Live verified	That named client reached this Ikuna helper through a real tool request.	You are ready.
Needs repair	The entry is missing, malformed, points to another Ikuna install or cannot be used.	Run setup with `--repair` or reconnect in Ikuna.

Recheck setup reads local configuration. It does not send a tool request, so it is not a live connection test.

Another MCP host

If guided setup does not detect your host, use Copy connection config in Ikuna or add the standard stdio entry below without replacing your other MCP servers.

{
  "mcpServers": {
    "ikuna": {
      "command": "npx",
      "args": ["-y", "ikuna-mcp"]
    }
  }
}

Codex uses TOML instead:

[mcp_servers.ikuna]
command = "npx"
args = ["-y", "ikuna-mcp"]
startup_timeout_sec = 30

Ollama does not read either configuration by itself. It can provide the model for a desktop host that supports MCP, but that host must start the Ikuna connection.

Privacy and control

The MCP server runs locally through Ikuna's signed helper.
Ikuna does not independently send prompts or activity history to a model provider.
Each client gets the permission scopes you select in AI Connections.
Sensitive window-title and URL access is separate from ordinary activity reads.
Every request appears in Ikuna's local access history.
Disconnect removes Ikuna's entry and preserves the host's other MCP servers.
Workspace changes and Focus Shield actions require the applicable permission and confirmation.

Troubleshooting

The client was already running

Quit and reopen it, or use its reconnect command. Most clients read MCP configuration when they start.

Ikuna moved or was reinstalled

Open the Ikuna copy you want to use, quit extra running copies, then run npx -y ikuna-mcp setup --repair.

The config conflicts with an existing entry

Guided setup backs up the client configuration and changes only Ikuna's entry. Run repair, or copy the connection config from Ikuna and compare that entry without deleting other servers.

The client says a tool is unavailable or denied

Open AI Connections and check that client's permissions. Installing the npm bridge does not grant activity, sensitive-context or workspace-control access.

The client cannot find npx

Run command -v npx in Terminal and use the returned full path as the config's command. Make sure the client can see the same Node.js installation.

A developer workflow, not another cloud account

Ikuna 1.2.6 pairs the npx MCP path with Zed workspace restore. Save a project with its Zed roots, files and tabs, then let an MCP-capable coding client query the focus and workspace context you allow. Zed is part of the restored project environment; your AI client is the MCP host.

See the 1.2.6 release Ikuna for developers

FAQ

Does Ikuna send my prompts or activity history to a model provider?

No. Ikuna does not transmit either on its own. Your AI client asks Ikuna for data through the local connection, and Ikuna returns only what that client's permissions allow. Your chosen client and model provider have their own privacy terms.

Is Ollama an MCP client?

No. Ollama is a local model runtime. You still need an MCP-capable desktop host that can start Ikuna's server. That host may use an Ollama model behind it.

Can a connected client change my workspaces?

Only when you grant workspace-control permission. Activity read access does not grant control. Sensitive window-title and URL access is separate too.

Does MCP need to be enabled to use Ikuna?

No. MCP is optional. Ikuna's workspace restore, Zed support, Focus Intelligence and the rest of the Mac app work without an AI connection.