OpenMemory MCP Troubleshooting Guide
About
Comprehensive troubleshooting guide for OpenMemory MCP server issues with Claude Desktop and other MCP clients
Explore
- Docker‑based setup instructions for OpenMemory
- Verification steps for Docker containers and API health
- SSE endpoint testing with a sample Node.js script
- Quick diagnostics shell script for automated checks
- Memory formatting guidelines (plain text, no markdown)
- Alternative Claude Desktop configurations and common issue solutions
Setting up with Highlight
This MCP is not yet compatible with Highlight’s one-click setup. However, you can still use it with Highlight by following these steps:
- Download and install Highlight from highlightai.com/download
- Navigate to the plugins tab and select "Add Custom Plugin"
-
Configure the plugin with the settings below
Plugin Name
OpenMemory MCP Troubleshooting GuideCommand (node, npx, python, etc.)Please refer to the README for specific instructions on how to obtain API keys or other required environment variables.
- Enable "Start Automatically" if you want the plugin to start when Highlight launches
From the repository
Before troubleshooting, ensure you have:
- Docker Desktop running
- Node.js and npm installed
- OpenAI API key
- Git
cd api
cp .env.example .env
Edit your Claude Desktop configuration file:
- macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
- Windows: %APPDATA%\Claude\claude_desktop_config.json
Add the OpenMemory configuration:
{
"mcpServers": {
"openmemory": {
"command": "npx",
"args": [
"-y",
"@modelcontextprotocol/server-sse",
"http://localhost:8765/mcp/claude/sse/ian"
]
}
}
}
If the standard configuration doesn't work, try these alternatives:
{
"mcpServers": {
"openmemory": {
"command": "npx",
"args": [
"-y",
"@modelcontextprotocol/server-sse@latest",
"http://localhost:8765/mcp/claude/sse/ian"
],
"env": {
"NODE_ENV": "production",
"DEBUG": "mcp:*"
}
}
}
}
Symptom: Connection refused errors
Solution: Start Docker Desktop and run make up again
Create diagnose.sh:
#!/bin/bash
echo "=== OpenMemory MCP Diagnostics ==="
echo
echo "1. Checking Docker..."
if docker ps > /dev/null 2>&1; then
echo "✓ Docker is running"
echo " OpenMemory containers:"
docker ps | grep openmemory | awk '{print " - " $NF}'
else
echo "✗ Docker is not running"
fi
echo
echo "2. Checking API..."
if curl -s http://localhost:8765/health > /dev/null 2>&1; then
echo "✓ API is responding"
else
echo "✗ API is not responding"
fi
echo
echo "3. Checking UI..."
if curl -s http://localhost:3001 > /dev/null 2>&1; then
echo "✓ UI is accessible"
else
echo "✗ UI is not accessible"
fi
echo
echo "4. Checking SSE endpoint..."
timeout 2 curl -s -N -H "Accept: text/event-stream" http://localhost:8765/mcp/claude/sse/ian > /dev/null 2>&1
if [ $? -eq 124 ]; then
echo "✓ SSE endpoint is streaming"
else
echo "✗ SSE endpoint is not working"
fi
echo
echo "5. Checking npm/npx..."
if command -v npx > /dev/null 2>&1; then
echo "✓ npx is available"
else
echo "✗ npx is not found"
fi
Make it executable and run:
chmod +x diagnose.sh
./diagnose.sh
Claude Desktop / Cursor
Paste into your MCP client config file to install this server.
{
"mcpServers": {
"openmemory mcp troubleshooting guide": {
"openmemory-mcp-troubleshooting": {
"command": "docker",
"args": [
"logs",
"openmemory-api-1",
"--tail",
"50"
]
}
}
}
}McpServers
{
"openmemory-mcp-troubleshooting": {
"command": "docker",
"args": [
"logs",
"openmemory-api-1",
"--tail",
"50"
]
}
}This repository contains comprehensive troubleshooting documentation for OpenMemory MCP Server integration with Claude Desktop and other MCP clients.
Common Error: "Server transport closed unexpectedly"
This is the most common error when setting up OpenMemory MCP:
2025-05-30T19:18:27.723Z [info] [openmemory] Server transport closed unexpectedly, this is likely due to the process exiting early.
2025-05-30T19:18:27.724Z [error] [openmemory] Server disconnected.
Prerequisites
Before troubleshooting, ensure you have:
- Docker Desktop running
- Node.js and npm installed
- OpenAI API key
- Git
Setup Process
1. Clone and Setup OpenMemory
```bash
Sign in to leave a review
Use Google, GitHub, or an email account so ratings stay tied to real people.
No reviews posted yet.
