OpenMemory MCP Troubleshooting Guide

OpenMemory MCP トラブルシューティングガイド

このリポジトリには、Claude Desktop やその他の MCP クライアントと連携する OpenMemory MCP Server の包括的なトラブルシューティングドキュメントが含まれています。

よくあるエラー：「Server transport closed unexpectedly」

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 Desktop が起動している
• 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 ui

2. サービスの稼働状況を確認する

# 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/ian

3. Claude Desktop を設定する

Claude Desktop の設定ファイルを編集します。

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
• Windows: %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)

トラブルシューティングの手順

ステップ 1：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 キーがない

症状：サーバーは起動するものの、すぐに切断される 解決策：openmemory/api/.env に OPENAI_API_KEY が設定されていることを確認してください

問題 2：Docker が起動していない

症状：接続拒否エラーが発生する 解決策：Docker Desktop を起動し、再度 make up を実行してください

問題 3：ポートの競合

症状：アドレスがすでに使用されているというエラーが発生する 解決策：ポート 8765 または 3001 を使用しているプロセスを終了してください

問題 4：SSE クライアントが見つからない

症状：コマンドが見つからないというエラーが発生する 解決策：グローバルにインストールしてください：npm install -g @modelcontextprotocol/server-sse

問題 5：CORS の問題

症状：ログにクロスオリジンエラーが表示される 解決策：localhost には https:// ではなく http:// を使用していることを確認してください

クイック診断スクリプト

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 など）が利用できる
• http://localhost:3001 の Web UI に接続中のクライアントが表示される

参考資料

• OpenMemory のドキュメント
• MCP のドキュメント
• Claude Desktop MCP ガイド

コントリビューション

追加の問題や解決策を見つけた場合は、ぜひ PR を提出して、ほかの人の役に立ててください！