Omi MCP Server

Omi MCP 服务

此项目提供了一个用于与 Omi API 交互的模型上下文协议（MCP）服务。该服务提供用于读取对话和记忆的工具，也可用于创建新的对话和记忆。

设置

1. 克隆仓库
2. 使用 npm install 安装依赖项
3. 创建包含以下变量的 .env 文件：

   API_KEY=your_api_key
   APP_ID=your_app_id
   

使用方法

通过 Smithery 安装

通过 Smithery 自动为 Claude Desktop 安装 Omi MCP Server：

npx -y @smithery/cli install @fourcolors/omi-mcp --client claude

构建服务

npm run build

运行服务

npm run start

开发模式

在开发过程中启用热重载：

npm run dev

测试服务

项目附带一个用于与 MCP 服务交互的简单测试客户端。构建项目后，运行：

npm run test

或直接运行：

./test-mcp-client.js

这将启动 MCP 服务，并提供一个交互式菜单，用于测试可用工具。测试客户端在所有操作中均使用默认测试用户 ID（test-user-123）。

清理并重新构建

清理构建目录并从头重新构建：

npm run rebuild

在 Claude 和 Cursor 中配置

Claude 配置

要通过 Anthropic Console 或 API 将此 MCP 服务与 Claude 配合使用：

1. 在本地启动 MCP 服务：

   npm run start
   

2. 设置 Claude 对话时，配置 MCP 连接：

   {
   	"mcp_config": {
   		"transports": [
   			{
   				"type": "stdio",
   				"executable": {
   					"path": "/path/to/your/omi-mcp-local/dist/index.js",
   					"args": []
   				}
   			}
   		]
   	}
   }
   

3. 提供给 Claude 的提示词示例：

   Please fetch the latest 5 conversations for user "user123" using the Omi API.
   

4. Claude 将使用 MCP 执行 read_omi_conversations 工具：

   {
   	"id": "req-1",
   	"type": "request",
   	"method": "tools.read_omi_conversations",
   	"params": {
   		"user_id": "user123",
   		"limit": 5
   	}
   }
   

Cursor 配置

要将此 MCP 服务与 Cursor 配合使用：

1. 在终端中启动 MCP 服务：

   npm run start
   

2. 在 Cursor 中，前往 Settings > Extensions > MCP Servers

3. 添加新的 MCP 服务，并使用以下设置：

   • 名称：Omi API
   • URL：stdio:/path/to/your/omi-mcp-local/dist/index.js
   • 启用服务

4. 现在，你可以直接在 Cursor 中使用 Omi 工具。例如：

   @Omi API Please fetch memories for user "user123" and summarize them.
   

5. Cursor 将与 MCP 服务通信，以执行所需的 API 调用。

可用工具

MCP 服务提供以下工具：

read_omi_conversations

读取特定用户在 Omi 中的对话，并可选择应用筛选条件。

参数：

• user_id（字符串）：要获取对话的用户 ID
• limit（数字，可选）：返回的最大对话数量
• offset（数字，可选）：分页时跳过的对话数量
• include_discarded（布尔值，可选）：是否包含已丢弃的对话
• statuses（字符串，可选）：用于筛选对话的状态列表，以逗号分隔

read_omi_memories

读取特定用户在 Omi 中的记忆。

参数：

• user_id（字符串）：要获取记忆的用户 ID
• limit（数字，可选）：返回的最大记忆数量
• offset（数字，可选）：分页时跳过的记忆数量

create_omi_conversation

为特定用户在 Omi 中创建新对话。

参数：

• text（字符串）：对话的完整文本内容
• user_id（字符串）：要为其创建对话的用户 ID
• text_source（字符串）：文本内容的来源（选项：“audio_transcript”、“message”、“other_text”）
• started_at（字符串，可选）：对话／事件开始时间（ISO 8601 格式）
• finished_at（字符串，可选）：对话／事件结束时间（ISO 8601 格式）
• language（字符串，可选）：语言代码（默认值：“en”）
• geolocation（对象，可选）：对话的位置数据
  • latitude（数字）：纬度坐标
  • longitude（数字）：经度坐标
• text_source_spec（字符串，可选）：有关来源的其他说明

create_omi_memories

为特定用户在 Omi 中创建新记忆。

参数：

• user_id（字符串）：要为其创建记忆的用户 ID
• text（字符串，可选）：用于提取记忆的文本内容
• memories（数组，可选）：要直接创建的显式记忆对象数组
  • content（字符串）：记忆内容
  • tags（字符串数组，可选）：记忆标签
• text_source（字符串，可选）：文本内容的来源
• text_source_spec（字符串，可选）：有关来源的其他说明

测试

要测试 MCP 服务，可以使用提供的测试客户端：

node test-mcp-client.js

这将启动一个交互式测试客户端，你可以使用它来：

1. 获取对话
2. 获取记忆
3. 创建对话
4. 退出

测试客户端在所有操作中都使用默认测试用户 ID（test-user-123）。

日志记录

MCP 服务内置日志功能，可将日志同时写入控制台和日志文件。这有助于调试和监控服务活动。

日志文件位置

日志写入项目目录中的 logs/mcp-server.log。日志文件包含时间戳以及以下详细信息：

• 服务启动和关闭
• 所有 API 请求和响应
• 错误消息和堆栈跟踪
• 对 Omi 的 API 调用
• 请求参数和响应数据

查看日志

你可以使用 tail 命令实时查看日志：

tail -f logs/mcp-server.log

这样，你就可以在服务处理请求并与 Omi API 交互时查看实时更新。

日志格式

每条日志条目都遵循以下格式：

[2024-03-21T12:34:56.789Z] Log message here

时间戳采用 ISO 8601 格式，便于关联事件和调试问题。