Omi MCP Server
The Omi MCP Server enables interaction with the Omi API for managing conversations and memories for specific users.
Key capabilities include:
Retrieve Conversations: Fetch user conversations with pagination, filtering by status, and options to include discarded conversations
Retrieve Memories: Access user memories with pagination options
Create Conversations: Generate new conversations with text content, metadata (geolocation, timestamps), and source information
Create Memories: Create memories by extracting from text or directly providing memory objects with optional tags
Integration Options: Compatible with Claude (via Anthropic Console or API) and Cursor for streamlined API calls
Logging and Testing: Includes built-in logging for debugging and a test client for validating functionality
Handles environment variable configuration for the MCP server to store API keys and application IDs for Omi API authentication
Used for package management and running script commands to build, start, and test the MCP server
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@Omi MCP Server fetch the last 3 conversations for user alice-jones"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
Omi MCP Server
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
Clone the repository
Install dependencies with
npm installCreate a
.envfile with the following variables:API_KEY=your_api_key APP_ID=your_app_id
Related MCP server: Omi Memories MCP Server
Usage
Installing via Smithery
To install Omi MCP Server for Claude Desktop automatically via Smithery:
npx -y @smithery/cli install @fourcolors/omi-mcp --client claudeBuilding the Server
npm run buildRunning the Server
npm run startDevelopment Mode
For development with hot-reloading:
npm run devTesting the Server
A simple test client is included to interact with the MCP server. After building the project, run:
npm run testOr directly:
./test-mcp-client.jsThis 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:
npm run rebuildConfiguration with Claude and Cursor
Claude Configuration
To use this MCP server with Claude via Anthropic Console or API:
Start the MCP server locally:
npm run startWhen 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": [] } } ] } }Example prompt to Claude:
Please fetch the latest 5 conversations for user "user123" using the Omi API.Claude will use the MCP to execute the
read_omi_conversationstool:{ "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:
Start the MCP server in a terminal:
npm run startIn Cursor, go to Settings > Extensions > MCP Servers
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
Now you can use the Omi tools directly within Cursor. For example:
@Omi API Please fetch memories for user "user123" and summarize them.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 forlimit(number, optional): Maximum number of conversations to returnoffset(number, optional): Number of conversations to skip for paginationinclude_discarded(boolean, optional): Whether to include discarded conversationsstatuses(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 forlimit(number, optional): Maximum number of memories to returnoffset(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 conversationuser_id(string): The user ID to create the conversation fortext_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 conversationlatitude(number): Latitude coordinatelongitude(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 fortext(string, optional): The text content from which memories will be extractedmemories(array, optional): An array of explicit memory objects to be created directlycontent(string): The content of the memorytags(array of strings, optional): Tags for the memory
text_source(string, optional): Source of the text contenttext_source_spec(string, optional): Additional specification about the source
Testing
To test the MCP server, you can use the provided test client:
node test-mcp-client.jsThis will start an interactive test client that allows you to:
Get conversations
Get memories
Create a conversation
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:
tail -f logs/mcp-server.logThis 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 hereThe timestamp is in ISO 8601 format, making it easy to correlate events and debug issues.
Available Tools
4 toolscreate_omi_conversationC
Creates a new Omi conversation with text content and metadata
Inputs: text (required), text_source (required), user_id (required), finished_at, +4 more.
create_omi_memoriesB
Creates Omi memories by extracting from text or using explicit memory objects
Inputs: user_id (required), memories, text, text_source, +1 more.
read_omi_conversationsC
Retrieves user conversations from Omi with pagination and filtering options
Inputs: user_id (required), include_discarded, limit, offset, +1 more.
read_omi_memoriesB
Retrieves user memories from Omi with pagination options
Inputs: user_id (required), limit, offset.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 4 tools
Each tool has a clearly distinct purpose: create vs. read operations for two distinct resources (conversations and memories). The separation between conversations and memories is explicit, and the create/read distinction is unambiguous, leaving no room for confusion or misselection.
All tool names follow a consistent verb_noun pattern with 'create' or 'read' as the verb and 'omi_conversations' or 'omi_memories' as the noun. The naming is perfectly uniform, using snake_case throughout, making the set highly predictable and readable.
With 4 tools, the count is reasonable for a server focused on Omi conversations and memories. It covers create and read operations for both resources, which is well-scoped, though it might feel slightly thin if update or delete operations are expected in the domain, but it's not a significant issue.
The tool set provides create and read operations for both conversations and memories, covering basic CRUD elements. However, there are notable gaps: no update or delete tools for either resource, which could limit agent workflows if modifications or deletions are needed, making the surface incomplete for full lifecycle management.
Maintenance
Related MCP Connectors
A comprehensive Model Context Protocol (MCP) server that enables AI assistants to interact with yo…
A Model Context Protocol server for Wix AI tools
Persistent memory for AI agents to retain, retrieve, and recall conversation context through MCP.
An MCP memory server. One memory your agents share — across models, devices and apps.
Related MCP Servers
- AlicenseNot gradedqualityDmaintenanceA Model Context Protocol server implementation that provides a standardized interface for applications to interact with OpenRouter's language models through a unified conversation management system.2MIT
- AlicenseDqualityDmaintenanceA Model Context Protocol server that enables access to Omi memories from a specific user account through a tool interface.12ISC
- AlicenseNot gradedqualityDmaintenanceA Model Context Protocol server that provides AI agents with persistent memory capabilities through Mem0, allowing them to store, retrieve, and semantically search memories.687MIT
- AlicenseNot gradedqualityDmaintenanceA Model Context Protocol server that integrates AI assistants with Mem0.ai's persistent memory system, allowing models to store, retrieve, search, and manage different types of memories.17MIT