Setup guide

Connecting OmniMem to Claude Desktop

Claude Desktop is Anthropic's desktop app for macOS and Windows. It talks to local MCP servers over stdio, so a server on a URL like OmniMem needs a small bridge, mcp-remote, to translate between the two. It's one line of config, honestly.

(Not to be confused with the OmniMem desktop app, which is the thing running your memory server. You can happily run both.)

Prerequisites

Install mcp-remote globally, or let npx fetch it on first run:

npm install -g mcp-remote

Finding your Claude Desktop config file

Claude Desktop keeps its MCP servers in claude_desktop_config.json:

OS Path
macOS ~/Library/Application Support/Claude/claude_desktop_config.json
Windows %APPDATA%\Claude\claude_desktop_config.json

On macOS you can open it from a terminal:

open ~/Library/Application\ Support/Claude/claude_desktop_config.json

On Windows, press Win+R and paste:

%APPDATA%\Claude\claude_desktop_config.json

If the file doesn't exist yet, create it containing {} and restart Claude Desktop.

Setup

Running the OmniMem desktop app? Click its tray or menu bar icon and choose Add to Claude Desktop, then restart Claude Desktop, and skip the rest of this section. It adds the entry below to your config, keeping a copy of the file as it was (claude_desktop_config.json.omnimem-backup). It checks first, so OmniMem is never added twice, and if your config already has an omnimem server pointing somewhere else (a 6.x install) the item offers to switch that entry here instead.

To do it by hand:

1. Grab the MCP URL. In the OmniMem desktop app, click the tray or menu bar icon and choose Copy MCP URL. On a local install it's http://127.0.0.1:8765/mcp.

2. Add OmniMem to your Claude Desktop config:

{
  "mcpServers": {
    "omnimem": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-remote",
        "http://127.0.0.1:8765/mcp"
      ]
    }
  }
}

3. Restart Claude Desktop. OmniMem should show up as a connected server.

With an access token

If you've set an access token (MCP_AUTH_TOKEN, or Access token on the OmniMem Configuration page):

{
  "mcpServers": {
    "omnimem": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-remote",
        "http://127.0.0.1:8765/mcp",
        "--header",
        "Authorization: Bearer your-token-here"
      ]
    }
  }
}

Coming from 6.x

6.x served SSE at /sse and needed --allow-http. Neither applies any more: change the URL to /mcp and drop the flag.

Why does Claude Desktop need mcp-remote?

Claude Desktop launches MCP servers as local processes and talks to them over standard input and output. It doesn't connect to an HTTP endpoint itself. mcp-remote sits in the middle: Claude Desktop starts it as a stdio process and it forwards everything to OmniMem over HTTP.

Claude Code doesn't have this problem, it connects to /mcp directly.

Remote access

If OmniMem runs on another machine, point the bridge at that URL:

{
  "mcpServers": {
    "omnimem": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-remote",
        "https://omnimem.yourdomain.com/mcp",
        "--header",
        "Authorization: Bearer your-token-here"
      ]
    }
  }
}

See remote access for reverse proxies, tunnels and OAuth.

Verifying the connection

After restarting Claude Desktop, start a new conversation and ask:

Can you call the OmniMem health tool?

You should get back the record and vector counts per namespace, whether the embedding model is loaded, and how long the server has been up.

Troubleshooting

By Ric HarveyUpdated All guidesThis guide on Forgejo