# iKho MCP

> 把 iKho 的录音、逐字稿与智能笔记接进任何兼容 MCP 的 AI 客户端。搜索录音、读取逐字稿、生成文档,全程不离开你的 AI 助手。

开发者平台处于内测阶段。接口契约以联调时提供的正式文档为准;账号由对接工程师开通,见联系我们。

## 支持的客户端

安装器会自动探测本机的 AI 客户端,写入 MCP 配置并打开浏览器完成登录。

  | 客户端 | 自动配置 | 安装后重启 

  | Claude Desktop | 是 | ⌘Q 退出后重新打开 
| Claude Code | 是 | 退出后新开一个 claude 会话 
| Cursor | 是 | 按客户端提示重新加载 
| Windsurf | 是 | 按客户端提示重新加载 
| VS Code | 是 | 按客户端提示重新加载 
| 任何 MCP 兼容客户端 | 手动配置 | 见下方「手动配置」与「远程接入」 

## 前置条件

  
- Node.js 20 或更高版本
  
- 一个 iKho 账号(内测账号由对接工程师开通,见联系我们)

## 安装

运行一次即可。安装器会探测本机的 AI 客户端,写入 MCP 配置,并打开浏览器登录:

  bash
    
  

  
```
npx -y @ikho/mcp@latest install
```

浏览器打开后点「授权」,再按安装器输出的提示重启对应客户端。下一个会话里 iKho 工具即可用。

内测阶段,@ikho/mcp 的包名与正式安装源随账号开通邮件一并发放,请以邮件中的说明为准。

## 手动配置

如果你的客户端没有被自动探测到,把下面这段粘进客户端的 MCP 配置即可:

  json
    
  

  
```
{
  "mcpServers": {
    "ikho": {
      "command": "npx",
      "args": ["-y", "@ikho/mcp@latest"]
    }
  }
}
```

## 远程接入(HTTP 客户端)

网页端等基于 HTTP 的客户端无需本地安装,在客户端的「自定义连接器 / Remote MCP」设置里填入远程服务地址 https://mcp.ikho.cn/mcp(内测),按提示完成授权即可。

通过远程地址接入时,你的录音数据全程只在境内节点处理,请求完成即焚、不做留存,数据不出境。

## 快速开始

装好后,先在 AI 客户端里登录:

登录 iKho
浏览器会打开 iKho 授权页,点「授权」后回到客户端即完成登录。随后可以尝试:

列出我最近的录音
把周一例会整理成跟进邮件

## 工具

连接 iKho MCP 后,以下工具会提供给你的 AI 客户端:

  | 工具 | 说明 

  | login | 打开浏览器完成 OAuth 登录 
| logout | 退出登录并吊销授权 
| get_current_user | 显示当前登录的账号信息 
| list_files | 列出你的录音,支持可选筛选 
| get_file | 返回单条录音的完整详情 
| get_note | 返回 iKho 智能引擎生成的摘要、待办事项与关键议题 
| get_transcript | 返回带时间戳与说话人标注的完整逐字稿 

### 用 list_files 筛选录音

  | 参数 | 说明 

  | query | 对录音名称做大小写不敏感的关键词匹配 
| date_from | 起始日期,格式 YYYY-MM-DD 
| date_to | 结束日期,格式 YYYY-MM-DD 
| page / page_size | 分页参数(设置了筛选条件时忽略) 

## 数据字段参考

### list_files 与 get_file 返回的字段

  | 字段 | 类型 | 说明 

  | id | string | 录音的唯一标识 
| name | string | 录音名称 
| created_at | string | 创建时间(ISO 8601) 
| start_at | string | 录音开始时间(ISO 8601) 
| duration | number | 时长(毫秒) 
| serial_number | string | 设备序列号 

### 仅 get_file 返回的字段

  | 字段 | 类型 | 说明 

  | presigned_url | string | 临时音频下载地址(24 小时内有效) 
| source_list | array | 带时间戳与说话人标注的逐字稿分段 
| note_list | array | iKho 智能引擎生成的笔记(Markdown) 

## 技能

技能是预置好的操作说明,帮助 AI 客户端自动完成常见的 iKho 工作流。它们随安装器一并加载,无需额外配置。

  | 技能 | 触发语句示例 

  | ikho-browse | 「列出我的录音」「显示最近的文件」 
| ikho-find | 「找一下周一的销售拜访」「上周三的门诊随访」 
| ikho-read | 「显示这段逐字稿」「把这条录音总结一下」 
| ikho-digest | 「本周工作周报」「这周我开了哪些会」 
| ikho-followup | 「起草一封跟进邮件」「列出待办事项」 

## 升级

  bash
    
  

  
```
npm install -g @ikho/mcp@latest
```

升级后重启你的 AI 客户端。

## 卸载

移除全局包并清理本地数据:

  bash
    
  

  
```
npm uninstall -g @ikho/mcp
rm -rf ~/.ikho
```

## 故障排查

  | 现象 | 处理方式 

  | 安装后客户端里不出现 iKho 工具 | 确认已完整重启客户端,仅关闭窗口不够;Claude Code 需退出后新开一个 claude 会话。 
| 报 401 /「未认证」 | 对 AI 客户端说:「登录 iKho」。 
| 登录时浏览器没有弹出 | 复制安装器在终端里打印的地址,手动在浏览器打开;在无界面机器上,先把本地回调端口转发到本机。 
| 令牌刷新失败 | 删除 ~/.ikho/tokens-mcp.json 后重新登录。 
| 升级后版本没更新 | 重新运行 npx -y @ikho/mcp@latest install,再重启客户端。 
| Claude Desktop 显示「服务器已断开」 | 重新运行安装 npx -y @ikho/mcp@latest install,再重启 Claude Desktop。