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.

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
   

To install Omi MCP Server for Claude Desktop automatically via Smithery:

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

npm run build

npm run start

For development with hot-reloading:

npm run dev

A simple test client is included to interact with the MCP server. After building the project, run:

npm run test

Or directly:

./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.

To clean the build directory and rebuild from scratch:

npm run rebuild

To use this MCP server with Claude via Anthropic Console or API:

1. Start the MCP server locally:

   npm run start

2. When setting up your Claude conversation, configure the MCP connection:

   {
   	"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:

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

To use this MCP server with Cursor:

1. Start the MCP server in a terminal:

   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.

The MCP server provides the following tools:

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

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

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

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

To test the MCP server, you can use the provided test client:

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.

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.

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

You can view the logs in real-time using the tail command:

tail -f logs/mcp-server.log

This will show you live updates as the server processes requests and interacts with the Omi API.

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.