Omi MCP

🚀 Omi MCP Server

This project provides a Model Context Protocol (MCP) server that interacts with the Omi API. The server offers tools for reading conversations and memories, as well as creating new ones.

🚀 Quick Start

After installation, run:

npm start

Then visit http://localhost:3000 to use the provided test client.

📦 Installation

Dependencies

• Node.js (Version requirement: 14.17.0 or higher)
• npm (Version requirement: 6.0.0 or higher)

Installation Steps

1. Clone the repository:

   git clone https://github.com/your-repository.git
   cd your-repository
   

2. Install dependencies:

   npm install
   

⚙️ Configuration Guide

Environment Variables

Create a .env file and add the following content:

OMI_API_KEY=your-api-key-here
PORT=3000

Server Startup

Run the following command to start the server:

npm start

🔧 Tool Instructions

Get Conversations

Request URL

• GET /conversations

Query Parameters

• userId: Required, string type, user ID.

Response Format

{
  "data": [
    {
      "id": string,
      "content": string,
      "source": string,
      "createdAt": string,
      "updatedAt": string
    }
  ],
  "message": string
}

Get Memories

Request URL

• GET /memories

Query Parameters

• userId: Required, string type, user ID.

Response Format

{
  "data": [
    {
      "id": string,
      "content": string,
      "tags": [string],
      "source": string,
      "createdAt": string,
      "updatedAt": string
    }
  ],
  "message": string
}

Create a Conversation

Request Method

• POST /conversations

Request Body Parameters

{
  "content": string,        // Conversation content
  "source": string,         // Content source, optional values: audio_transcript, message, other_text
  "startedAt": string,      // Start time (ISO 8601 format)
  "finishedAt": string,     // End time (ISO 8601 format)
  "language": string,       // Language code, default is en
  "geolocation": {
    "latitude": number,     // Latitude coordinate
    "longitude": number     // Longitude coordinate
  },
  "sourceSpec": string      // Additional description of the content source
}

Create Memories

Request Method

• POST /memories

Request Body Parameters

{
  "text": string,          // Text content (optional)
  "memories": [
    {
      "content": string,    // Content
      "tags": [string]     // Array of tags (optional)
    }
  ],
  "source": string,         // Content source (optional)
  "sourceSpec": string      // Additional description of the content source (optional)
}

🧪 Testing

Use the provided test client for testing:

node test-mcp-client.js

This will start an interactive test client that allows you to perform the following operations:

1. Get conversations
2. Get memories
3. Create a conversation
4. Exit

All operations use the default test user ID (test-user-123).

📝 Logging

The MCP server includes built-in logging functionality, which by default outputs logs to the console and files. This is very useful for debugging and monitoring server activities.

Log File Location

Logs are written to the logs/mcp-server.log file. The log content includes:

• Server startup and shutdown
• All API requests and responses
• Error messages and stack traces
• Omi API call records
• Request parameters and response data

View Logs

Use the following command to view logs in real-time:

tail -f logs/mcp-server.log

Log Format

Each log record has the following format:

[2024-03-21T12:34:56.789Z] Log message here

The timestamp uses the ISO 8601 format for easy event correlation and debugging.