Omi MCP 服务器

本项目提供了一个模型上下文协议 (MCP) 服务器，用于与 Omi API 交互。该服务器提供了读取对话和记忆以及创建新对话和记忆的工具。

设置

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

   API_KEY=你的_api_key
   APP_ID=你的_app_id
   

用法

通过 Smithery 安装

要通过 Smithery 为 Claude Desktop 自动安装 Omi MCP 服务器：

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 的示例提示：

   请使用 Omi API 获取用户 "user123" 的最新 5 个对话。
   

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 服务器，并使用以下设置：

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

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

   @Omi API 请获取用户 "user123" 的记忆并进行总结。
   

5. Cursor 将与您的 MCP 服务器通信以执行必要的 API 调用。

可用工具

MCP 服务器提供以下工具：

read_omi_conversations

从 Omi 检索特定用户的对话，带有可选的过滤器。

参数：

• user_id (string): 要获取对话的用户 ID
• limit (number, optional): 要返回的最大对话数
• offset (number, optional): 要跳过的对话数，用于分页
• include_discarded (boolean, optional): 是否包括已丢弃的对话
• statuses (string, optional): 以逗号分隔的状态列表，用于过滤对话

read_omi_memories

从 Omi 检索特定用户的记忆。

参数：

• user_id (string): 要获取记忆的用户 ID
• limit (number, optional): 要返回的最大记忆数
• offset (number, optional): 要跳过的记忆数，用于分页

create_omi_conversation

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

参数：

• text (string): 对话的完整文本内容
• user_id (string): 要创建对话的用户 ID
• text_source (string): 文本内容的来源（选项："audio_transcript"、"message"、"other_text"）
• started_at (string, optional): 对话/事件开始的时间（ISO 8601 格式）
• finished_at (string, optional): 对话/事件结束的时间（ISO 8601 格式）
• language (string, optional): 语言代码（默认："en"）
• geolocation (object, optional): 对话的位置数据
  • latitude (number): 纬度坐标
  • longitude (number): 经度坐标
• text_source_spec (string, optional): 关于来源的附加说明

create_omi_memories

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

参数：

• user_id (string): 要创建记忆的用户 ID
• text (string, optional): 将从中提取记忆的文本内容
• memories (array, optional): 要直接创建的显式记忆对象的数组
  • content (string): 记忆的内容
  • tags (array of strings, optional): 记忆的标签
• text_source (string, optional): 文本内容的来源
• text_source_spec (string, optional): 关于来源的附加说明

测试

要测试 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] 日志消息在这里

时间戳采用 ISO 8601 格式，可以轻松关联事件和调试问题。