Ikuna

Name: Ikuna
Author: RobertoHanas

本地服务

npmjs.com生产力06 周前更新

代码仓库访问官网

关于 Ikuna

Ikuna 是本地 MCP 服务，让 AI 客户端读取正在运行的 Ikuna macOS 应用中的工作区上下文和活动。共享范围与审批由 Ikuna 管理。

主要功能

01读取工作区上下文和活动
02使用应用管理的能力与审批
03发现正在运行的 Ikuna 安装
04引导客户端配置与修复
05本地桥接，不开放网络监听

适用场景

01通过 AI 客户端查询工作区上下文
02仅共享已启用的 Ikuna 能力
03配置或修复检测到的客户端

MCP 相关

该服务通过本地 XPC 连接，将 MCP 客户端桥接到正在运行的 Ikuna 应用内置原生助手。可用工具、数据、审批和修改均由 Ikuna 控制。

配置

本地服务的配置在各客户端中通用，复制后粘贴到客户端的 MCP 配置文件即可。

mcp.json · 通用配置

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

启动命令npx -y ikuna-mcp

本地服务需要在你的电脑上安装运行环境（如 Node.js 18+）。各客户端的配置文件位置不同，请参考客户端文档。

安装包

npmikuna-mcp0.2.0stdio

工具

还没有获取到工具列表

本地服务需要在你的电脑上运行后才能读取工具，维护者暂未提供工具列表。

详细介绍

Ikuna MCP

将 AI 客户端连接到 Mac 上运行的 Ikuna 应用中的工作区上下文。

ikuna-mcp 0.1.1 已作为 io.github.RobertoHanas/ikuna-mcp 列入官方 MCP Registry。

连接

安装 Node.js 18 或更高版本，并确保包含 npx。
打开 Ikuna，并在 设置 → AI 连接中启用你想共享的功能。
运行引导式设置：

npx -y ikuna-mcp setup

设置程序会检测 Claude Desktop、Codex、Claude Code 和 Cursor，只将 Ikuna 的条目合并到它们现有的配置中，保留最新的 3 个备份，并验证本地 MCP 握手。重新运行同一命令可修复过时或缺失的值，也可以明确指定此操作：

npx -y ikuna-mcp setup --repair
npx -y ikuna-mcp setup --client codex

退出状态 0 表示所有检测到的客户端均已完成配置，且握手通过；1 表示配置已保存，但验证仍需手动完成；2 表示没有检测到可完成配置的客户端。

如果某个客户端未被自动检测到，请将以下条目添加到其 mcpServers 配置中，同时保留其他服务：

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

对于 Claude Desktop、Claude Code 和 Cursor 等客户端，完整的 JSON 配置如下：

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

对于 Codex，请将以下内容添加到 ~/.codex/config.toml：

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

保存后重启或重新连接 MCP 客户端。请它检查 Ikuna 的运行状况，然后询问你的工作区。你可用的工具取决于 Ikuna 中启用的功能。

首次运行时会从 npm 下载这个小型软件包。之后的运行会使用 npm 缓存。如果客户端找不到 npx，请将 command -v npx 报告的完整可执行文件路径用作 command，并确保客户端的 PATH 中包含 Node.js。

要求和故障排除

此软件包在 macOS 本地运行。它需要包含 MCP 辅助程序 Contents/bin/ikuna-mcp 的 Ikuna 版本。

**已安装 Ikuna，但应用已关闭：**打开 Ikuna，让它保持运行，然后重新连接 MCP 客户端。Ikuna 关闭时，npm 桥接程序会报错退出；它不会替你打开应用。
**未安装 Ikuna：**从 Ikuna 官方产品页面安装并打开，然后重新连接 MCP 客户端。
**MCP 辅助程序不可用：**将 Ikuna 更新到支持 AI 连接的版本。
**发现超时：**退出并重新打开 Ikuna，然后重试。运行中应用的发现时限较短，错误会写入 stderr，不会与 MCP 响应混在一起。
**同时运行多个 Ikuna 副本：**退出多余的副本。所有副本共用本地桥接服务，因此同一时间只使用一个正在运行的安装实例。
**工具不可用或需要批准：**检查 Ikuna 的 AI 连接设置中的功能。安装此软件包不会更改权限。

系统会自动发现自定义安装位置中的正在运行的应用。如需明确选择某个正在运行的程序包：

"ikuna": {
  "command": "npx",
  "args": ["-y", "ikuna-mcp", "--app-path", "/Applications/Ikuna.app"]
}

IKUNA_APP_PATH 是等效的环境变量。所选程序包必须已经在运行。可选的 IKUNA_MCP_CLIENT_ID 环境变量会传递给 Ikuna，用于连接记录；它不会授予访问权限。

工作原理

MCP client → npx ikuna-mcp → Ikuna.app/Contents/bin/ikuna-mcp → local XPC bridge → Ikuna

npm 软件包会发现正在运行的 Ikuna 程序包，并使用客户端的标准输入输出流启动其内置的原生辅助程序。原生辅助程序负责提供经过签名的 XPC 连接、请求时限和每个客户端的协议会话。工具、工作区数据、审批和变更均由 Ikuna 负责。返回客户端的过程中，软件包会修正 tools/list 架构，确保可选的确认字段保持可选，并避免严格的客户端拒绝有效的读取调用；它不会更改任何请求、工作区数据或结果。此软件包没有运行时依赖，不读取工作区数据库，也不会打开网络监听器。

MCP Registry 清单以 server.json 的形式随附。维护者可按照 RELEASE.md 同时发布 npm 软件包和条目。

支持 Markdown

登录后评论