* 目次 [#n77b39e8]
#contents
** はじめに [#fd16e3ea]
Claude DesktopでNeo4jを使おうとして create_entities や create_relations でエラーが出て困っていませんか？本記事では、現在のmcp-neo4jで発生するCypher構文エラーの原因と解決方法を詳しく解説します。
** Neo4jとCypher構文の基礎 [#l9c8e8a1]
*** Neo4jとは [#z05c88ff]
Neo4jは''グラフデータベース''の代表的な製品です。従来のリレーショナルデータベース（MySQL、PostgreSQLなど）が表形式でデータを管理するのに対し、Neo4jは''ノード（点）''と''関係性（線）''でデータを表現します。
例えば：
- 人物（ノード）同士の友人関係（関係性）
- 商品（ノード）とカテゴリ（ノード）の所属関係
- 概念（ノード）間の因果関係
*** Cypher構文とは [#z0ca4913]
CypherはNeo4j専用のクエリ言語です。SQLと似ていますが、グラフ構造に特化した記法を持ちます。
''基本的な書き方：''
// ノード作成
CREATE (p:Person {name: \"Alice\", age: 30})
// 関係性作成
MATCH (a:Person {name: \"Alice\"}), (b:Person {name: \"Bob\"})
CREATE (a)-[:FRIEND]->(b)
// データ検索
MATCH (p:Person)-[:FRIEND]->(friend)
WHERE p.name = \"Alice\"
RETURN friend.name
** AIとNeo4jの組み合わせの価値 [#e4d8a96f]
*** 従来の手動クエリの課題 [#g909458c]
これまでNeo4jを使うには：
+ Cypher構文を覚える必要がある
+ 複雑なクエリは書くのが困難
+ データ構造を正確に把握している必要がある
*** AIによる自然言語アクセス [#me692b05]
MCPでClaude DesktopとNeo4jを接続すると：
- 「Aliceの友人を教えて」→ 自動でCypherクエリ生成
- 「2つの概念の関係性を調べて」→ 複雑な関係性探索
- 「知識グラフを更新して」→ 自然言語でのデータ追加
|''従来''|プログラマーがCypherを書く|
|''AI活用''|自然言語で指示、AIが適切なクエリを実行|
** MCPで接続する理由 [#df3da250]
*** MCPとは [#r156b225]
MCP（Model Context Protocol）は、AIモデルが外部システムと安全に連携するためのプロトコルです。Claude DesktopではMCPサーバーを通じて様々な外部システムにアクセスできます。
*** Neo4jをMCPで接続するメリット [#hf6d4a85]
+ ''リアルタイムアクセス''
-- 会話中にその場でデータを検索・更新
-- 動的な知識グラフの構築
+ ''自然言語インターフェース''
-- 技術的な知識なしでグラフデータベースを活用
-- 複雑な関係性分析を直感的に実行
+ ''知識の蓄積・進化''
-- 会話で得た情報を構造化して保存
-- 時間とともに成長する個人知識ベース
** 現在の問題：Cypher構文エラー [#o3186d99]
*** 発生するエラー [#u362ce48]
現在の公式mcp-neo4jには重大なバグがあります：
{code: Neo.ClientError.Statement.SyntaxError}
{message: Invalid input '$': expected an identifier (line 5, column 15 (offset: 144))
\" SET e:$(entity.type)\"
*** エラーの原因 [#q0d0a846]
問題は''間違ったCypher構文''にあります：
''❌ 現在の問題のあるコード（推定）：''
CREATE (e:Knowledge)
SET e:$(entity.type) // 無効な構文
SET e.name = $(entity.name) // 間違ったパラメータ構文
''✅ 正しいCypher構文：''
CREATE (e:Knowledge {
name: $name, // 正しいパラメータ構文
type: $type, // ラベルではなくプロパティとして保存
observations: $observations
})
*** 影響範囲 [#j4796ed3]
- create_entities 関数が完全に動作しない
- create_relations 関数も同様のエラー
- 知識グラフの作成が不可能
- MCPサーバーの主要機能が使用不能
*** PRの状況 [#n26822a3]
私はこの問題の修正を含むPull Requestを提出しましたが、残念ながら理解が得られずクローズされてしまいました。技術的には正しい修正でしたが、修正の必要性や影響範囲を十分に伝えられなかったことが原因です。
** 解決策：修正版の使用 [#hd771dab]
*** 修正版のインストール [#o9e9e027]
私のフォークで修正版を公開していますので、以下の手順でインストールできます：
# 修正版をインストール
npm install https://github.com/khayashi4337/mcp-neo4j.git#fix-cypher-syntax
# または、ローカルでクローンして使用
# 修正版をローカルでクローンして使用
git clone https://github.com/khayashi4337/mcp-neo4j.git
cd mcp-neo4j
git checkout fix-cypher-syntax
npm install
*** Claude Desktop設定例 [#b04585fa]
私の実際の設定を参考に、以下のように設定してください：
自分はdockerでneo4jのサーバをうごかしているのですが、以下の私の実際の設定を参考に設定してください：
{
\"mcpServers\": {
\"neo4j-memory\": {
\"command\": \"C:\\\\your-workspace\\\\mcp-neo4j\\\\servers\\\\mcp-neo4j-memory\\\\.venv\\\\Scripts\\\\python.exe\",
\"args\": [\"-m\", \"mcp_neo4j_memory\"],
\"env\": {
\"NEO4J_URL\": \"neo4j://localhost:7687\",
\"NEO4J_USERNAME\": \"your_username\",
\"NEO4J_PASSWORD\": \"your_password\"
}
}
"mcpServers": {
"neo4j-memory": {
"command": "I:\\xxxxx\\.venv\\Scripts\\python.exe",
"args": ["-m", "mcp_neo4j_memory"],
"env": {
"NEO4J_URL": "neo4j://localhost:7687",
"NEO4J_USERNAME": "neo4j",
"NEO4J_PASSWORD": "password123"
}
}
}
}
''設定のポイント：''
- your_username と your_password は実際のNeo4j認証情報に置き換えてください
- パスの C:\\\\your-workspace\\\\ 部分は、あなたの実際のワークスペースパスに変更してください
- 私はNeo4jをDocker Desktopで起動させています。これにより環境の管理が簡単になり、他のプロジェクトとの競合も避けられます
- Docker Desktopでneo4jを起動している場合、デフォルトポート7687で接続できます
*** はまりがちな設定ポイント [#r8e11250]
''1. 設定ファイルの場所''
- Windows: %APPDATA%\\Claude\\claude_desktop_config.json
- Mac: ~/Library/Application Support/Claude/claude_desktop_config.json
''2. JSON形式の注意点''
- カンマの位置に注意
- 最後の項目にはカンマを付けない
- 文字列は必ずダブルクォートで囲む
''3. パス指定''
- Windowsでは \\\\ でパスを区切る
- 絶対パスの使用を推奨
''4. 仮想環境の作成''
cd mcp-neo4j/servers/mcp-neo4j-memory
python -m venv .venv
.venv\\Scripts\\activate # Windows
pip install -e .
** 動作確認 [#ca5ac3c6]
*** 1. Claude Desktop再起動 [#ocf5d1d8]
設定変更後は必ずClaude Desktopを完全に再起動してください。
*** 2. 接続確認 [#reee3711]
Claude Desktopで以下のように確認できます：
Neo4jに接続できていますか？
*** 3. 基本的な動作テスト [#q2c54d05]
「テスト」という名前の知識エンティティを作成してください。
正常に動作すれば、エラーなくエンティティが作成されるはずです。
** 修正内容の詳細 [#v55fafb8]
*** 主な修正点 [#w82b65a6]
+ ''正しいCypherパラメータ構文''
-- $(variable) → $variable
+ ''動的ラベルの代替手法''
-- ラベルを直接操作する代わりに、プロパティとして保存
+ ''トランザクション管理''
-- データ整合性の向上
-- エラー時のロールバック
+ ''エラーハンドリング強化''
-- 詳細なエラー情報の提供
-- 分かりやすいエラーメッセージ
** 今後の展望 [#c9c1e3ee]
*** 公式版での修正 [#v353ab76]
現在クローズされていますが、将来的に公式版でも修正される可能性があります。その際は公式版への移行をお勧めします。
*** 修正版のメンテナンス [#l7289f81]
私のフォーク版は以下の方針で維持します：
- 公式版の更新に追従
- 重要なバグ修正の継続
- コミュニティからのフィードバック対応
** まとめ [#h1c9c336]
mcp-neo4jは非常に有用なツールですが、現在のCypher構文エラーにより本来の機能を発揮できません。修正版を使用することで：
- 知識グラフの作成が可能になる
- Claude DesktopでNeo4jを自然言語で操作できる
- 個人の知識ベースシステムが構築できる
同じ問題で困っている方の参考になれば幸いです。質問やフィードバックがありましたら、お気軽にコメントください。
----
''関連リンク：''
- [[GitHub Issue #67>https://github.com/neo4j-contrib/mcp-neo4j/issues/67]]
- [[修正版リポジトリ>https://github.com/khayashi4337/mcp-neo4j]]
- [[Neo4j公式ドキュメント>https://neo4j.com/docs/]]`,
`filename`: `mcp-neo4j Cypher構文エラー解決記事_pukiwiki.txt`
