mcp-arangodb-async

Python 用 ArangoDB MCP サーバー

Claude Desktop や Augment Code などの AI アシスタントに、高度な ArangoDB 操作を提供する、本番環境で利用可能な Model Context Protocol（MCP）サーバーです。非同期処理を第一に考えた Python アーキテクチャ、包括的なグラフ管理、柔軟なコンテンツ変換（JSON、Markdown、YAML、テーブル）、バックアップ／復元機能、分析機能を備えています。

クイックリンク

📚 ドキュメント： https://github.com/PCfVW/mcp-arango-async/tree/master/docs

🚀 クイックスタート： https://github.com/PCfVW/mcp-arango-async/blob/master/docs/getting-started/quickstart.md

🔧 ArangoDB のセットアップ： https://github.com/PCfVW/mcp-arango-async/blob/master/docs/getting-started/install-arangodb.md

🗄️ マルチテナンシーガイド： https://github.com/PCfVW/mcp-arango-async/blob/master/docs/user-guide/multi-tenancy-guide.md

⚙️ CLI リファレンス： https://github.com/PCfVW/mcp-arango-async/blob/master/docs/user-guide/cli-reference.md

📖 ツールリファレンス： https://github.com/PCfVW/mcp-arango-async/blob/master/docs/user-guide/tools-reference.md

🎯 MCP 設計パターン： https://github.com/PCfVW/mcp-arango-async/blob/master/docs/user-guide/mcp-design-patterns.md

📝 変更履歴： https://github.com/PCfVW/mcp-arango-async/blob/master/docs/developer-guide/changelog.md

🐛 課題： https://github.com/PCfVW/mcp-arango-async/issues

機能

• ✅ 46 個の MCP ツール - ArangoDB の完全な操作機能（クエリ、コレクション、インデックス、グラフ）
• ✅ マルチテナンシー - 複数のデータベースの利用、環境の切り替え、データベース間操作
• ✅ MCP 設計パターン - 段階的な検出、コンテキストの切り替え、ツールのアンロード（トークンを 98.7% 節約）
• ✅ グラフ管理 - 名前付きグラフの作成、走査、バックアップ／復元
• ✅ コンテンツ変換 - JSON、Markdown、YAML、テーブル形式
• ✅ バックアップ／復元 - 検証機能付きのコレクション単位およびグラフ単位のバックアップ
• ✅ 分析 - クエリのプロファイリング、実行計画の説明、グラフ統計
• ✅ デュアルトランスポート - stdio（デスクトップクライアント）と HTTP（ウェブ／コンテナ環境）
• ✅ Docker サポート - 分離性と再現性を備えた Docker での実行
• ✅ 本番環境対応 - 再試行ロジック、適切な縮退動作、包括的なエラー処理
• ✅ 型安全 - すべてのツール引数を Pydantic で検証

アーキテクチャ

┌────────────────────┐      ┌─────────────────────┐       ┌──────────────────┐
│   MCP Client       │      │  ArangoDB MCP       │       │   ArangoDB       │
│ (Claude, Augment)  │─────▶│  Server (Python)    │─────▶│  (Docker)        │
│                    │      │  • 46 Tools         │       │  • Multi-Model   │
│                    │      │  • Multi-Tenancy    │       │  • Graph Engine  │
│                    │      │  • Graph Mgmt       │       │  • AQL Engine    │
│                    │      │  • MCP Patterns     │       │                  │
└────────────────────┘      └─────────────────────┘       └──────────────────┘

ArangoDB を使い始める

前提条件

• Docker と Docker Compose がインストールされていること
• Python 3.11+（mcp-arangodb-async 用）

手順 1：ArangoDB をインストールする

docker-compose.yml ファイルを作成します。

services:
  arangodb:
    image: arangodb:3.11
    environment:
      ARANGO_ROOT_PASSWORD: ${ARANGO_ROOT_PASSWORD:-changeme}
    ports:
      - "8529:8529"
    volumes:
      - arangodb_data:/var/lib/arangodb3
      - arangodb_apps:/var/lib/arangodb3-apps
    healthcheck:
      test: arangosh --server.username root --server.password "$ARANGO_ROOT_PASSWORD" --javascript.execute-string "require('@arangodb').db._version()" > /dev/null 2>&1 || exit 1
      interval: 5s
      timeout: 2s
      retries: 30
    restart: unless-stopped

volumes:
  arangodb_data:
    driver: local
  arangodb_apps:
    driver: local

.env ファイルを作成します。

# ArangoDB root password
ARANGO_ROOT_PASSWORD=changeme

# MCP Server connection settings
ARANGO_URL=http://localhost:8529
ARANGO_DB=mcp_arangodb_test
ARANGO_USERNAME=mcp_arangodb_user
ARANGO_PASSWORD=mcp_arangodb_password

ArangoDB を起動します。

docker compose --env-file .env up -d

ステップ 2：mcp-arangodb-async をインストールする

MCP サーバーパッケージをインストールします：

pip install mcp-arangodb-async

# Create environment and install
conda create -n mcp-arango python=3.11
conda activate mcp-arango
pip install mcp-arangodb-async

# Or with mamba/micromamba:
# mamba create -n mcp-arango python=3.11
# mamba activate mcp-arango
# pip install mcp-arangodb-async

# Create environment and install
uv venv .venv --python 3.11
uv pip install mcp-arangodb-async

ステップ 3：データベースとユーザーを作成する

MCP サーバー用のデータベースとユーザーを作成します：

maa db add mcp_arangodb_test \
  --url http://localhost:8529 \
  --with-user mcp_arangodb_user \
  --env-file .env

想定される出力：

The following actions will be performed:
  [ADD] Database 'mcp_arangodb_test'
  [ADD] User 'mcp_arangodb_user' (active: true)
  [GRANT] Permission rw: mcp_arangodb_user → mcp_arangodb_test

Are you sure you want to proceed? [y/N]: y
db add:
[ADDED] Database 'mcp_arangodb_test'
[ADDED] User 'mcp_arangodb_user' (active: true)
[GRANTED] Permission rw: mcp_arangodb_user → mcp_arangodb_test

データベース接続を確認します：

# Set environment variables
export ARANGO_URL=http://localhost:8529
export ARANGO_DB=mcp_arangodb_test
export ARANGO_USERNAME=mcp_arangodb_user
export ARANGO_PASSWORD=mcp_arangodb_password

# Run health check
maa health

想定される出力：

{"status": "healthy", "database_connected": true, "database_info": {"version": "3.11.x", "name": "mcp_arangodb_test"}}

ステップ 4：MCP ホストを設定する

サーバーを使用するように MCP ホストを設定します。設定には、データベース接続用の環境変数が含まれます。設定ファイルの場所は、使用する MCP ホストによって異なります。Claude Desktop の場合、ファイルは次の場所にあります：

• Windows： %APPDATA%\Claude\claude_desktop_config.json
• macOS： ~/Library/Application Support/Claude/claude_desktop_config.json
• Linux： ~/.config/Claude/claude_desktop_config.json

設定：

{
  "mcpServers": {
    "arangodb": {
      "command": "python",
      "args": ["-m", "mcp_arangodb_async"],
      "env": {
        "ARANGO_URL": "http://localhost:8529",
        "ARANGO_DB": "mcp_arangodb_test",
        "ARANGO_USERNAME": "mcp_arangodb_user",
        "ARANGO_PASSWORD": "mcp_arangodb_password"
      }
    }
  }
}

{
  "mcpServers": {
    "arangodb": {
      "command": "conda",
      "args": ["run", "-n", "mcp-arango", "maa", "server"],
      "env": {
        "ARANGO_URL": "http://localhost:8529",
        "ARANGO_DB": "mcp_arangodb_test",
        "ARANGO_USERNAME": "mcp_arangodb_user",
        "ARANGO_PASSWORD": "mcp_arangodb_password"
      }
    }
  }
}

{
  "mcpServers": {
    "arangodb": {
      "command": "uv",
      "args": ["run", "--directory", "/path/to/project", "maa", "server"],
      "env": {
        "ARANGO_URL": "http://localhost:8529",
        "ARANGO_DB": "mcp_arangodb_test",
        "ARANGO_USERNAME": "mcp_arangodb_user",
        "ARANGO_PASSWORD": "mcp_arangodb_password"
      }
    }
  }
}

設定を更新した後、MCP クライアントを再起動してください。

接続をテストする：

MCP クライアントに次のように尋ねます："ArangoDB データベース内のすべてのコレクションを一覧表示してください"

アシスタントが正常に接続し、コレクションを一覧表示できるはずです。

使用可能なツール

このサーバーは、11 カテゴリに分類された 46 個の MCP ツールを公開します：

マルチテナンシーツール（4 個）

• arango_set_focused_database - セッションでフォーカスするデータベースを設定
• arango_get_focused_database - 現在フォーカスしているデータベースを取得
• arango_list_available_databases - 設定済みのすべてのデータベースを一覧表示
• arango_get_database_resolution - データベース解決アルゴリズムを表示

コアデータ操作（7 個）

• arango_query - AQL クエリを実行
• arango_list_collections - すべてのコレクションを一覧表示
• arango_insert - ドキュメントを挿入
• arango_update - ドキュメントを更新
• arango_remove - ドキュメントを削除
• arango_create_collection - コレクションを作成
• arango_backup - コレクションをバックアップ

インデックス管理（3 個）

• arango_list_indexes - インデックスを一覧表示
• arango_create_index - インデックスを作成
• arango_delete_index - インデックスを削除

クエリ分析（3 個）

• arango_explain_query - クエリ実行計画を説明
• arango_query_builder - AQL クエリを作成
• arango_query_profile - クエリのパフォーマンスをプロファイリング

データ検証（4 個）

• arango_validate_references - ドキュメント参照を検証
• arango_insert_with_validation - 検証しながら挿入
• arango_create_schema - JSON スキーマを作成
• arango_validate_document - スキーマに照らして検証

一括操作（2 個）

• arango_bulk_insert - ドキュメントを一括挿入
• arango_bulk_update - ドキュメントを一括更新

グラフ管理（7 個）

• arango_create_graph - 名前付きグラフを作成
• arango_list_graphs - すべてのグラフを一覧表示
• arango_add_vertex_collection - 頂点コレクションを追加
• arango_add_edge_definition - エッジ定義を追加
• arango_add_vertex - 頂点を追加
• arango_add_edge - エッジを追加
• arango_graph_traversal - グラフをトラバース

グラフトラバーサル（2 個）

• arango_traverse - グラフトラバーサル
• arango_shortest_path - 最短経路を検索

グラフのバックアップ／復元（5 個）

• arango_backup_graph - 単一グラフをバックアップ
• arango_restore_graph - 単一グラフを復元
• arango_backup_named_graphs - すべての名前付きグラフをバックアップ
• arango_validate_graph_integrity - グラフの整合性を検証
• arango_graph_statistics - グラフの統計情報

ヘルスとステータス（1 個）

• arango_database_status - すべてのデータベースの詳細なステータスを取得

ツールエイリアス（2 ツール）

• arango_graph_traversal - arango_traverse のエイリアス
• arango_add_vertex - arango_insert のエイリアス

MCP 設計パターンツール（8 ツール）

• arango_search_tools - キーワードでツールを検索
• arango_list_tools_by_category - カテゴリ別にツールを一覧表示
• arango_switch_workflow - ワークフローのコンテキストを切り替え
• arango_get_active_workflow - アクティブなワークフローを取得
• arango_list_workflows - すべてのワークフローを一覧表示
• arango_advance_workflow_stage - ワークフローのステージを進める
• arango_get_tool_usage_stats - ツールの使用統計を取得
• arango_unload_tools - 特定のツールをアンロード

📖 ツールの完全なリファレンス： https://github.com/PCfVW/mcp-arango-async/blob/master/docs/user-guide/tools-reference.md

📖 MCP 設計パターンガイド： https://github.com/PCfVW/mcp-arango-async/blob/master/docs/user-guide/mcp-design-patterns.md

使用例：コードベースのグラフ分析

コードベースをグラフとしてモデル化し、依存関係の分析、循環参照の検出、アーキテクチャの把握を行います。以下は、より詳しいコードベース分析の例からの抜粋です。

# 1. Create graph structure
Ask Claude: "Create a graph called 'codebase' with vertex collections 'modules' and 'functions', and edge collection 'calls' connecting functions"

# 2. Import codebase data
Ask Claude: "Insert these modules into the 'modules' collection: [...]"

# 3. Analyze dependencies
Ask Claude: "Find all functions that depend on the 'auth' module using graph traversal"

# 4. Detect circular dependencies
Ask Claude: "Check for circular dependencies in the codebase graph"

# 5. Generate architecture diagram
Ask Claude: "Export the codebase graph structure as Markdown for visualization"

📖 その他の例

ドキュメント

はじめに

• ArangoDB のインストール
• クイックスタートガイド
• ソースからのインストール
• 最初のやり取り

設定

• トランスポートの設定
• 環境変数

ユーザーガイド

• ツールリファレンス
• トラブルシューティング

開発者ガイド

• アーキテクチャの概要
• 低レベル MCP の根拠
• HTTP トランスポート
• 変更履歴

例

• コードベースの依存関係分析

📖 ドキュメントの全容： https://github.com/PCfVW/mcp-arango-async/tree/master/docs

トラブルシューティング

よくある問題

データベースへの接続に失敗する場合：

# Check ArangoDB is running
docker ps | grep arangodb

# Test connection
curl http://localhost:8529/_api/version

# Check credentials
maa health

Claude Desktop でサーバーが起動しない場合：

# Verify Python installation
python --version  # Must be 3.11+

# Test module directly
maa health

# Check Claude Desktop logs
# Windows: %APPDATA%\Claude\logs\
# macOS: ~/Library/Logs/Claude/

ツールの実行エラー：

• ArangoDB が正常に動作していることを確認します：docker compose ps
• 環境変数が正しく設定されていることを確認します
• 詳細なエラーメッセージについては、サーバーのログを確認します

📖 トラブルシューティングガイドの全容

ArangoDB に Docker を使う理由

✅ 安定性 - 環境を分離し、ホストとの競合を防ぎます
✅ インストール不要 - docker compose で起動・停止できます
✅ 再現性 - すべての環境で同じイメージを使用できます
✅ ヘルスチェック - 組み込みの準備状況検証機能
✅ 迅速なリセット - クリーンなインスタンスを簡単に再作成できます
✅ 移植性 - Windows／macOS／Linux で一貫して動作します

ライセンス

• このプロジェクト： Apache License 2.0
• ArangoDB 3.11： Apache License 2.0
• ArangoDB 3.12 以降： Business Source License 1.1（BUSL-1.1）

⚠️ 重要： このリポジトリは ArangoDB バイナリの使用権を付与するものではありません。デプロイするバージョンに適用される ArangoDB のライセンスに従う必要があります。

📖 ライセンスの詳細

コントリビューション

コントリビューションを歓迎します！ガイドラインについては、ドキュメントをご覧ください。

📖 アーキテクチャ上の決定事項

サポート

• 課題
• ディスカッション
• ドキュメント

謝辞

以下を使用して構築されています：

• Anthropic による Model Context Protocol
• python-arango - ArangoDB 公式 Python ドライバー
• Pydantic - データ検証
• Starlette - HTTP トランスポート
• ArangoDB - マルチモデルデータベース