Omi MCP Server

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

安装

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

   API_KEY=your_api_key
   APP_ID=your_app_id
   

使用方法

通过 Smithery 安装

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

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 配置

要在 Cursor 中使用此 MCP 服务器：

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

   npm run start
   

2. 在 Cursor 中，进入设置 > 扩展 > MCP 服务器

3. 添加具有以下设置的新 MCP 服务器：

   • 名称：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 (字符串)：要获取对话的用户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] 日志消息在此处

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