Skip to main content
Glama
Omi MCP Server

Omi MCP Server

by fourcolors

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

  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

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 claude

Building the Server

npm run build

Running the Server

npm run start

Development Mode

For development with hot-reloading:

npm run dev

Testing the Server

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.

Clean and Rebuild

To clean the build directory and rebuild from scratch:

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:

    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
     }
    }

Cursor Configuration

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.

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:

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:

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.

Available Tools

4 tools
create_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

    B3.4/5.0

    Scored across 4 tools

    Disambiguation5/5

    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.

    Naming Consistency5/5

    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.

    Tool Count4/5

    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.

    Completeness3/5

    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

    ActivityInactive
    ResponsivenessOutdated data

    Related MCP Connectors

    Related MCP Servers