OpenMemory MCP故障排除指南
此存储库包含OpenMemory MCP Server与Claude Desktop和其他MCP客户端集成的全面故障排除文档。
常见错误：“服务器传输意外关闭”
这是设置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.先决条件
在排除故障之前，请确保您已经：
- Docker桌面正在运行
- 已安装Node.js和npm
- OpenAI API密钥
- Git
设置过程
1.克隆和设置OpenMemory
# Clone the repository
git clone https://github.com/mem0ai/mem0.git
cd openmemory
# Create and configure the .env file
cd api
cp .env.example .env
# Edit .env and add your OPENAI_API_KEY
echo "OPENAI_API_KEY=your_actual_api_key_here" > .env
cd ..
# Build Docker images
make build
# Start all services
make up
# Start the frontend
cp ui/.env.example ui/.env
make ui2.验证服务是否正在运行
# Check Docker containers
docker ps | grep openmemory
# You should see:
# - openmemory-api-1
# - openmemory-postgres-1
# - openmemory-qdrant-1
# Test API endpoint
curl http://localhost:8765/health
curl http://localhost:8765/docs
# Test SSE endpoint
curl -N -H "Accept: text/event-stream" http://localhost:8765/mcp/claude/sse/ian3.配置克劳德桌面
编辑您的Claude Desktop配置文件：
- macOS:
~/Library/Application Support/Claude/claude_desktop_config.json - 视窗:
%APPDATA%\Claude\claude_desktop_config.json
添加OpenMemory配置：
{
"mcpServers": {
"openmemory": {
"command": "npx",
"args": [
"-y",
"@modelcontextprotocol/server-sse",
"http://localhost:8765/mcp/claude/sse/ian"
]
}
}
}重要提示：内存格式化指南
使用OpenMemory存储内存时，请遵循以下准则以获得最佳效果：
✅ 做：
- 使用无特殊格式的纯文本
- 保持记忆简洁自然
- 将复杂信息拆分为逻辑块（摘要+详细信息）
- 用连篇散文而不是列表写作
- 让每段记忆都集中在一个主题或概念上
❌ 不要：
- 使用markdown格式（粗体、斜体、页眉）
- 创建编号或项目符号列表
- 添加换行符或复杂结构
- 输入非常长的条目
- 使用特殊字符或格式符号
示例-良好的内存格式：
Ian has 18 MCP servers installed in Claude Desktop for various automation and development tasks. The servers include applescript_execute for Mac system control, context7-mcp for documentation lookup, desktop-commander for file operations, and other tools for browser automation, task management, and screen capture.示例-内存格式不佳：
Ian's MCP Servers:
1. **applescript_execute** - Mac system control
2. **context7-mcp** - Documentation lookup
3. **desktop-commander** - File operations
... (long formatted list)故障排除步骤
第一步：检查Docker日志
# Check API logs for errors
docker logs openmemory-api-1 --tail 50
# Check for specific errors
docker logs openmemory-api-1 2>&1 | grep -i error第2步：验证API密钥
# Check if API key is set in the container
docker exec openmemory-api-1 env | grep OPENAI_API_KEY步骤3：测试SSE连接
创建测试文件 test-sse.js:
const EventSource = require('eventsource');
const es = new EventSource('http://localhost:8765/mcp/claude/sse/ian');
es.onopen = () => console.log('Connected to SSE');
es.onmessage = (event) => console.log('Message:', event.data);
es.onerror = (err) => console.error('Error:', err);
setTimeout(() => {
es.close();
console.log('Connection closed');
}, 10000);运行它：
npm install eventsource
node test-sse.js步骤4：替代配置
如果标准配置不起作用，请尝试以下替代方案：
选项1：使用包装脚本
创建 /Users/ian/openmemory-mcp.sh:
#!/bin/bash
exec npx -y @modelcontextprotocol/server-sse http://localhost:8765/mcp/claude/sse/ian使其可执行：
chmod +x /Users/ian/openmemory-mcp.sh更新Claude配置：
{
"mcpServers": {
"openmemory": {
"command": "/Users/ian/openmemory-mcp.sh",
"args": []
}
}
}选项2：使用环境变量
{
"mcpServers": {
"openmemory": {
"command": "npx",
"args": [
"-y",
"@modelcontextprotocol/server-sse@latest",
"http://localhost:8765/mcp/claude/sse/ian"
],
"env": {
"NODE_ENV": "production",
"DEBUG": "mcp:*"
}
}
}
}步骤5：检查端口可用性
# Check if port 8765 is in use
lsof -i :8765
# Check if port 3001 is in use (UI)
lsof -i :3001常见问题及解决方法
问题1：缺少API密钥
症状：服务器启动但立即断开连接 解决方案：确保在中设置了OPENAI_API_KEY openmemory/api/.env
问题2：Docker无法运行
症状：连接被拒绝错误 解决方案：启动Docker桌面并运行 make up 再次
问题3：港口冲突
症状：地址已在使用中错误 解决方案：使用端口8765或3001终止进程
问题4：未找到SSE客户端
症状：未找到命令错误 解决方案：全局安装： npm install -g @modelcontextprotocol/server-sse
问题5:CORS问题
症状：日志中的跨源错误 解决方案：确保使用 http:// 不 https:// 对于本地主机
快速诊断脚本
创建 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使其可执行并运行：
chmod +x diagnose.sh
./diagnose.sh工作示例
正确配置后，您应该在Claude Desktop中看到：
- OpenMemory出现在MCP服务器列表中
- 内存工具可用（add_Memory、search_Memory等）
- web UI位于http://localhost:3001显示已连接的客户端
额外资源
贡献
如果您发现其他问题或解决方案，请提交PR以帮助他人！
