Db MCP

🚀 db-mcp

OAuth 2.1認証と89の専用ツールを備えたエンタープライズグレードのSQLite MCPサーバー

ベータ版 - このプロジェクトは現在積極的に開発中であり、まだ本番環境での使用には適していません。

最大89のツール、OAuth 2.1認証、および細かなアクセス制御を備えたSQLite MCPサーバーです。TypeScriptで書かれています。

Wiki • 変更履歴 • セキュリティ

🚀 クイックスタート

🔍 目次

クイックスタート

• ✅ クイックテスト - すべてが正常に動作することを確認する
• 🚀 クイックスタート
• ⚡ Cursor IDEへのインストール

設定と使用方法

• 📚 MCPクライアントの設定
• 🎛️ ツールフィルタリングのプリセット
• 🎨 使用例
• 📊 ツールのカテゴリ

機能とリソース

• 🔥 核心機能
• 🔐 OAuth 2.1の実装
• 🏆 なぜdb-mcpを選ぶのか？
• 📈 プロジェクトの統計情報

✅ クイックテスト - すべてが正常に動作することを確認する

30秒でサーバーをテストしましょう！

ビルドして実行:

npm run build
node dist/cli.js --transport stdio --sqlite-native :memory:

期待される出力:

[db-mcp] MCPサーバーを起動中...
[db-mcp] アダプターを登録しました: Native SQLite Adapter (better-sqlite3) (sqlite:default)
[db-mcp] サーバーが正常に起動しました

テストスイートを実行:

npm run test

🛡️ セキュリティ機能

• ✅ SQLインジェクション防止 - すべてのクエリでパラメータバインディングを使用
• ✅ OAuth 2.1認証 - RFC 9728/8414準拠
• ✅ スコープベースの承認 - 細かな読み取り/書き込み/管理者アクセス
• ✅ Strict TypeScript - any型を使用せず、完全な型安全性

⬆️ 目次に戻る

🚀 クイックスタート

オプション1: Docker (推奨)

すぐにプルして実行:

docker pull writenotenow/db-mcp:latest

ボリュームマウントで実行:

docker run -i --rm \
  -v $(pwd):/workspace \
  writenotenow/db-mcp:latest \
  --sqlite-native /workspace/database.db

オプション2: Node.jsインストール

リポジトリをクローン:

git clone https://github.com/neverinfamous/db-mcp.git

ディレクトリに移動:

cd db-mcp

依存関係をインストール:

npm install

プロジェクトをビルド:

npm run build

サーバーを実行:

node dist/cli.js --transport stdio --sqlite-native ./database.db

⬆️ 目次に戻る

⚡ Cursor IDEへのインストール

ワンクリックインストール

以下のボタンをクリックして、Cursorに直接インストールします。

または、このディープリンクをコピーします。

cursor://anysphere.cursor-deeplink/mcp/install?name=db-mcp-sqlite&config=eyJkYi1tY3Atc3FsaXRlIjp7ImFyZ3MiOlsicnVuIiwiLWkiLCItLXJtIiwiLXYiLCIkKHB3ZCk6L3dvcmtzcGFjZSIsIndyaXRlbm90ZW5vdy9kYi1tY3A6bGF0ZXN0IiwiLS1zcWxpdGUtbmF0aXZlIiwiL3dvcmtzcGFjZS9kYXRhYmFzZS5kYiJdLCJjb21tYW5kIjoiZG9ja2VyIn19

前提条件

• ✅ Dockerがインストールされ、実行中であること (Dockerメソッドの場合)
• ✅ Node.js 18以上 (ローカルインストールの場合)

⬆️ 目次に戻る

📊 ツールのカテゴリ

SQLiteバックエンドのオプション

ニーズに応じて、2つのSQLiteバックエンドから選択できます。

トランザクションツール (7つ) - ネイティブのみ

ウィンドウ関数ツール (6つ) - ネイティブのみ

⬆️ 目次に戻る

📚 MCPクライアントの設定

Cursor IDE

{
  "mcpServers": {
    "db-mcp-sqlite": {
      "command": "node",
      "args": [
        "C:/path/to/db-mcp/dist/cli.js",
        "--transport", "stdio",
        "--sqlite-native", "C:/path/to/your/database.db"
      ]
    }
  }
}

Claude Desktop

{
  "mcpServers": {
    "db-mcp-sqlite": {
      "command": "node",
      "args": [
        "/path/to/db-mcp/dist/cli.js",
        "--transport", "stdio",
        "--sqlite-native", "/path/to/database.db"
      ]
    }
  }
}

DockerとClaude Desktop

{
  "mcpServers": {
    "db-mcp-sqlite": {
      "command": "docker",
      "args": [
        "run", "-i", "--rm",
        "-v", "/path/to/project:/workspace",
        "writenotenow/db-mcp:latest",
        "--sqlite-native", "/workspace/database.db"
      ]
    }
  }
}

インメモリデータベース

一時的なインメモリデータベースには :memory: を使用します。

{
  "args": ["--transport", "stdio", "--sqlite-native", ":memory:"]
}

⬆️ 目次に戻る

🎛️ ツールフィルタリングのプリセット

⚠️ 重要な注意

CursorのようなAI対応IDEにはツールの制限があります。ネイティブバックエンドには89のツールがあるため、制限内に収まるようにツールフィルタリングを使用する必要があります。以下のプリセットから、あなたのユースケースに合ったものを選択してください。

ツールグループ

プリセット: 最小限度 (~35ツール) ⭐ ほとんどのユーザーにおすすめ

JSONと基本的なテキストを含むコアデータベース操作。一般的な開発に最適。

{
  "mcpServers": {
    "db-mcp-sqlite": {
      "command": "node",
      "args": [
        "C:/path/to/db-mcp/dist/cli.js",
        "--transport", "stdio",
        "--sqlite-native", "C:/path/to/database.db",
        "--tool-filter", "-stats,-vector,-geo,-backup,-monitoring,-transactions,-window"
      ]
    }
  }
}

プリセット: 分析 (~56ツール)

統計、ウィンドウ関数、およびテキスト処理を含みます。データ分析に適しています。

{
  "args": [
    "--transport", "stdio",
    "--sqlite-native", "C:/path/to/database.db",
    "--tool-filter", "-vector,-geo,-backup,-monitoring"
  ]
}

プリセット: 検索 (~62ツール)

全文検索に加えて、ベクトル/セマンティック検索機能を備えています。

{
  "args": [
    "--transport", "stdio",
    "--sqlite-native", "C:/path/to/database.db",
    "--tool-filter", "-stats,-geo,-backup,-monitoring,-transactions,-window"
  ]
}

プリセット: 地理空間 (~48ツール)

距離計算、境界ボックス、および空間クエリ。

{
  "args": [
    "--transport", "stdio",
    "--sqlite-native", "C:/path/to/database.db",
    "--tool-filter", "-stats,-vector,-backup,-monitoring,-transactions,-window"
  ]
}

カスタムフィルタリング

以下の構文を使用して独自のフィルタを作成します。

• -group — グループ内のすべてのツールを無効にする
• -tool_name — 特定のツールを無効にする
• +tool_name — グループを無効にした後にツールを再有効にする

# 例: ベクトルと地理空間を無効にするが、cosine_similarityは有効にする
--tool-filter "-vector,-geo,+cosine_similarity"

⬆️ 目次に戻る

💻 使用例

データ分析ワークフロー

1. プロジェクトをビルド:

npm run build

2. データを使って開始:

node dist/cli.js --transport stdio --sqlite-native ./sales_data.db

3. Claude/Cursorと一緒に使用する:
   • データセットの統計分析
   • テキスト処理とパターン抽出
   • ベクトル類似性検索
   • 地理空間分析とマッピング

JSON操作

// JSONデータを挿入
sqlite_write_query({
  query: "INSERT INTO products (metadata) VALUES (?)",
  params: [JSON.stringify({ name: "Product", price: 29.99 })]
})

// パス抽出でJSONをクエリ
sqlite_json_extract({
  table: "products",
  column: "metadata",
  path: "$.price"
})

ベクトル/セマンティック検索

// 埋め込みを保存
sqlite_vector_store({
  table: "documents",
  id_column: "id",
  embedding_column: "embedding",
  id: 1,
  embedding: [0.1, 0.2, 0.3, ...]
})

// 類似するアイテムを検索
sqlite_vector_search({
  table: "documents",
  embedding_column: "embedding",
  query_embedding: [0.15, 0.25, 0.35, ...],
  top_k: 10
})

全文検索 (FTS5)

// FTS5インデックスを作成
sqlite_fts_create({
  table: "articles",
  columns: ["title", "content"]
})

// BM25ランキングで検索
sqlite_fts_search({
  table: "articles",
  query: "機械学習",
  limit: 10
})

統計分析

// 列の記述統計を取得
sqlite_describe_stats({
  table: "employees",
  column: "salary"
})
// 返り値: カウント、平均、標準偏差、最小値、25%、50%、75%、最大値

// パーセンタイルを計算
sqlite_percentile({
  table: "sales",
  column: "revenue",
  percentiles: [25, 50, 75, 90, 95, 99]
})

// ヒストグラムを生成
sqlite_histogram({
  table: "products",
  column: "price",
  bins: 10
})

地理空間操作

// 2点間の距離を計算 (ハーベサイン公式)
sqlite_geo_distance({
  lat1: 40.7128,
  lon1: -74.0060,  // ニューヨーク
  lat2: 34.0522,
  lon2: -118.2437  // ロサンゼルス
})
// 返り値: 距離 (キロメートル)

// 境界ボックス内の場所を検索
sqlite_geo_bounding_box({
  table: "stores",
  lat_column: "latitude",
  lon_column: "longitude",
  min_lat: 40.0,
  max_lat: 41.0,
  min_lon: -75.0,
  max_lon: -73.0
})

// 近くのポイントをクラスタリング
sqlite_geo_cluster({
  table: "customers",
  lat_column: "lat",
  lon_column: "lon",
  distance_km: 5
})

ウィンドウ関数 (ネイティブのみ)

// クエリ結果に行番号を追加
sqlite_window_row_number({
  table: "employees",
  order_by: "hire_date",
  partition_by: "department"
})

// ランキングを計算
sqlite_window_rank({
  table: "sales",
  value_column: "revenue",
  partition_by: "region",
  rank_type: "dense_rank"  // または "rank", "percent_rank"
})

// 累計合計を計算
sqlite_window_running_total({
  table: "transactions",
  value_column: "amount",
  order_by: "date",
  partition_by: "account_id"
})

// 移動平均
sqlite_window_moving_avg({
  table: "stock_prices",
  value_column: "close_price",
  order_by: "date",
  window_size: 7  // 7日間の移動平均
})

トランザクション (ネイティブのみ)

// 複数のステートメントを原子的に実行
sqlite_transaction_execute({
  statements: [
    "UPDATE accounts SET balance = balance - 100 WHERE id = 1",
    "UPDATE accounts SET balance = balance + 100 WHERE id = 2",
    "INSERT INTO transfers (from_id, to_id, amount) VALUES (1, 2, 100)"
  ]
})
// すべてのステートメントが成功するか、すべてロールバックされます。

// セーブポイントを使用した手動トランザクション制御
sqlite_transaction_begin({ mode: "immediate" })
sqlite_transaction_savepoint({ name: "before_update" })
// ... 操作を実行 ...
sqlite_transaction_rollback_to({ name: "before_update" })  // 必要に応じて元に戻す
sqlite_transaction_commit()

テキスト処理

// 正規表現パターンマッチング
sqlite_regex_match({
  table: "logs",
  column: "message",
  pattern: "ERROR:\\s+(\\w+)"
})

// スペルミスのファジー検索
sqlite_fuzzy_search({
  table: "products",
  column: "name",
  query: "laptp",  // "laptop" のスペルミス
  threshold: 0.6
})

// テキスト類似性スコアリング
sqlite_text_similarity({
  text1: "機械学習",
  text2: "ディープラーニング",
  algorithm: "levenshtein"  // または "jaro_winkler", "cosine"
})

⬆️ 目次に戻る

✨ 主な機能

• 📊 統計分析 - 記述統計、パーセンタイル、時系列分析
• 🔍 高度なテキスト処理 - 正規表現、ファジーマッチング、音韻検索、類似性
• 🧠 ベクトル/セマンティック検索 - AIネイティブの埋め込み、コサイン類似性、ハイブリッド検索
• 🗺️ 地理空間操作 - 距離計算、境界ボックス、空間クエリ
• 🔐 トランザクションの安全性 - セーブポイントを備えた完全なACID準拠 (ネイティブバックエンド)
• 🎛️ 89の専用ツール - 完全なデータベース管理と分析ツールセット

🏢 エンタープライズ機能

• 🔐 OAuth 2.1認証 - RFC 9728/8414準拠のトークンベースの認証
• 🛡️ ツールフィルタリング - 公開するデータベース操作を制御する
• 👥 アクセス制御 - 読み取り専用、書き込み、および管理者アクセスの細かなスコープ
• 🎯 全文検索 (FTS5) - BM25ランキングを備えた高度な検索
• ⚡ ウィンドウ関数 - 行番号、ランキング、累計合計、移動平均

⬆️ 目次に戻る

🔧 技術詳細

OAuth 2.1の実装

サポートされるスコープ

Keycloak統合

OAuthプロバイダとしてKeycloakを設定するには、docs/KEYCLOAK_SETUP.md を参照してください。

⬆️ 目次に戻る

🏆 なぜdb-mcpを選ぶのか

✅ TypeScriptネイティブ - 厳格モードで完全な型安全性、any型を使用せず ✅ 89の専用ツール - 最も包括的なSQLite MCPサーバー ✅ OAuth 2.1組み込み - エンタープライズグレードの認証がすぐに使える ✅ デュアルバックエンド - ポータビリティにはWASM、パフォーマンスにはネイティブ ✅ ツールフィルタリング - プリセット構成でAI IDEのツール制限内に収まる ✅ ウィンドウ関数 - ROW_NUMBER、RANK、LAG/LEADによる高度な分析 ✅ トランザクションサポート - セーブポイントを備えた完全なACID準拠 ✅ 最新のアーキテクチャ - MCP SDK上に構築され、クリーンでモジュール化された設計 ✅ 積極的な開発 - 定期的な更新と改善

⬆️ 目次に戻る

📈 プロジェクトの統計情報

• ネイティブバックエンドには89のツール (WASMには76)
• 柔軟なフィルタリングのための13のツールグループ
• 完全な型カバレッジのStrict TypeScript
• マルチプラットフォームサポート (Windows、Linux、macOS)
• 簡単なデプロイのためのDockerイメージ
• RFC準拠のOAuth 2.1認証
• 定期的な更新による積極的な開発

⬆️ 目次に戻る

設定

環境変数

.env.example を .env にコピーして設定します。

KEYCLOAK_URL=http://localhost:8080
KEYCLOAK_REALM=db-mcp
KEYCLOAK_CLIENT_ID=db-mcp-server
KEYCLOAK_CLIENT_SECRET=your_secret_here
DBMCP_PORT=3000
DBMCP_OAUTH_ENABLED=true

JSON設定

完全な例については、config/db-mcp.keycloak.json を参照してください。

コントリビュート

コントリビューションは大歓迎です！プルリクエストを送信する前に、コントリビューションガイドライン をお読みください。

セキュリティ

セキュリティに関する懸念事項については、セキュリティポリシー を参照してください。

⚠️ 重要な注意

資格情報を決してコミットしないでください - シークレットは .env (gitignoreされている) に保存してください。

📄 ライセンス

このプロジェクトはMITライセンスの下でライセンスされています - 詳細については LICENSE ファイルを参照してください。

行動規範

このプロジェクトに参加する前に、行動規範 をお読みください。