omi-mcp

# Omi MCP Server [](https://smithery.ai/server/@fourcolors/omi-mcp) This project provides a Model Context Protocol (MCP) server for interacting with the Omi API. The server provides tools for reading conversations and memories, as well as creating new conversations and memories. ## Setup 1. Clone the repository 2. Install dependencies with `npm install` 3. Create a `.env` file with the following variables: ``` API_KEY=your_api_key APP_ID=your_app_id ``` ## Usage ### Installing via Smithery To install Omi MCP Server for Claude Desktop automatically via [Smithery](https://smithery.ai/server/@fourcolors/omi-mcp): ```bash npx -y @smithery/cli install @fourcolors/omi-mcp --client claude ``` ### Building the Server ```bash npm run build ``` ### Running the Server ```bash npm run start ``` ### Development Mode For development with hot-reloading: ```bash npm run dev ``` ### Testing the Server A simple test client is included to interact with the MCP server. After building the project, run: ```bash npm run test ``` Or directly: ```bash ./test-mcp-client.js ``` This will start the MCP server and provide an interactive menu to test the available tools. The test client uses a default test user ID (`test-user-123`) for all operations. ### Clean and Rebuild To clean the build directory and rebuild from scratch: ```bash npm run rebuild ``` ## Configuration with Claude and Cursor ### Claude Configuration To use this MCP server with Claude via Anthropic Console or API: 1. Start the MCP server locally: ```bash npm run start ``` 2. When setting up your Claude conversation, configure the MCP connection: ```json { "mcp_config": { "transports": [ { "type": "stdio", "executable": { "path": "/path/to/your/omi-mcp-local/dist/index.js", "args": [] } } ] } } ``` 3. Example prompt to Claude: ``` Please fetch the latest 5 conversations for user "user123" using the Omi API. ``` 4. Claude will use the MCP to execute the `read_omi_conversations` tool: ```json { "id": "req-1", "type": "request", "method": "tools.read_omi_conversations", "params": { "user_id": "user123", "limit": 5 } } ``` ### Cursor Configuration To use this MCP server with Cursor: 1. Start the MCP server in a terminal: ```bash npm run start ``` 2. In Cursor, go to Settings > Extensions > MCP Servers 3. Add a new MCP server with these settings: - Name: Omi API - URL: stdio:/path/to/your/omi-mcp-local/dist/index.js - Enable the server 4. Now you can use the Omi tools directly within Cursor. For example: ``` @Omi API Please fetch memories for user "user123" and summarize them. ``` 5. Cursor will communicate with your MCP server to execute the necessary API calls. ## Available Tools The MCP server provides the following tools: ### read_omi_conversations Retrieves conversations from Omi for a specific user, with optional filters. Parameters: - `user_id` (string): The user ID to fetch conversations for - `limit` (number, optional): Maximum number of conversations to return - `offset` (number, optional): Number of conversations to skip for pagination - `include_discarded` (boolean, optional): Whether to include discarded conversations - `statuses` (string, optional): Comma-separated list of statuses to filter conversations by ### read_omi_memories Retrieves memories from Omi for a specific user. Parameters: - `user_id` (string): The user ID to fetch memories for - `limit` (number, optional): Maximum number of memories to return - `offset` (number, optional): Number of memories to skip for pagination ### create_omi_conversation Creates a new conversation in Omi for a specific user. Parameters: - `text` (string): The full text content of the conversation - `user_id` (string): The user ID to create the conversation for - `text_source` (string): Source of the text content (options: "audio_transcript", "message", "other_text") - `started_at` (string, optional): When the conversation/event started (ISO 8601 format) - `finished_at` (string, optional): When the conversation/event ended (ISO 8601 format) - `language` (string, optional): Language code (default: "en") - `geolocation` (object, optional): Location data for the conversation - `latitude` (number): Latitude coordinate - `longitude` (number): Longitude coordinate - `text_source_spec` (string, optional): Additional specification about the source ### create_omi_memories Creates new memories in Omi for a specific user. Parameters: - `user_id` (string): The user ID to create memories for - `text` (string, optional): The text content from which memories will be extracted - `memories` (array, optional): An array of explicit memory objects to be created directly - `content` (string): The content of the memory - `tags` (array of strings, optional): Tags for the memory - `text_source` (string, optional): Source of the text content - `text_source_spec` (string, optional): Additional specification about the source ## Testing To test the MCP server, you can use the provided test client: ```bash node test-mcp-client.js ``` This will start an interactive test client that allows you to: 1. Get conversations 2. Get memories 3. Create a conversation 4. Quit The test client uses a default test user ID (`test-user-123`) for all operations. ## Logging The MCP server includes built-in logging functionality that writes to both the console and a log file. This is useful for debugging and monitoring server activity. ### Log File Location Logs are written to `logs/mcp-server.log` in your project directory. The log file includes timestamps and detailed information about: - Server startup and shutdown - All API requests and responses - Error messages and stack traces - API calls to Omi - Request parameters and response data ### Viewing Logs You can view the logs in real-time using the `tail` command: ```bash tail -f logs/mcp-server.log ``` This will show you live updates as the server processes requests and interacts with the Omi API. ### Log Format Each log entry follows this format: ``` [2024-03-21T12:34:56.789Z] Log message here ``` The timestamp is in ISO 8601 format, making it easy to correlate events and debug issues.