Databases (read-only, switchable)

mcp-db-read-only

AI アシスタントに、データベースを変更できない状態で閲覧させることができます。

MySQL、PostgreSQL、SQLite、SQL Server、ClickHouse、MongoDB、Redis、Elasticsearch に接続し、自然な言葉で質問するだけです。「今週登録したユーザーは何人ですか？」「orders テーブルには何がありますか？」「セッションを保持している Redis キーはどれですか？」と尋ねてみましょう。アクセスを許可したデータはすべて読み取れますが、書き込み、更新、削除はできません。

• よく使われるデータベースをすべて、1つのサーバーで。 会話の途中で切り替えられます。
• 二重の読み取り専用。 クエリは送信前にチェックされ、データベース自体にも書き込みを拒否するよう指示されます。
• 切り替え時に再起動は不要。 データベース、サーバー、エンジンを頼むだけで変更できます。
• ログ記録は任意。 ブラウザーのライブページで、実行中のすべてのクエリを確認できます。

flowchart LR
    Y["You"] -->|"ask in plain words"| AI["Your AI assistant"]
    AI -->|"tool call"| S["mcp-db-read-only"]
    S -->|"read-only query"| DB[("Your databases")]
    DB -->|"rows, documents, keys"| S

Claude Desktop、Claude Code、およびその他のMCPクライアントで動作します。

---

クイックスタート

1. Node.js 22.13 以降（node --version）、または Docker を用意します。

2. MCP サーバーをクライアントに追加します。 Claude Desktop の場合は、claude_desktop_config.json を編集します（Settings、Developer、Edit Config）。Claude Code の場合は、プロジェクトに .mcp.json を作成します。

{
  "mcpServers": {
    "databases": {
      "command": "npx",
      "args": ["-y", "@shibbirweb/mcp-db-read-only"],
      "env": {
        "DB_URL": "postgres://readonly:secret@localhost:5432/myapp"
      }
    }
  }
}

DB_URL を使用するデータベースのものに置き換えます。以下の例では、各データベースの URL を紹介しています。

3. クライアントを一度再起動して、質問してみましょう。

「データベースにはどんなテーブルがありますか？」 「最新の注文を5件表示してください。」 「国ごとの顧客数を教えてください。」

これで完了です。データベースを変更する際に、再起動する必要はありません。アシスタントに切り替えを頼むだけです。

---

各データベースの例

各データベースについて、URL の形式と、コピーして変更できる実際の例を示します。完成した URL を DB_URL に設定してください。

各 [PLACEHOLDER] を自分の値に置き換えます。

プレースホルダー	設定する値
[USER]	データベースのユーザー名
[PASSWORD]	そのユーザーのパスワード
[HOST]	サーバーのアドレス。例：localhost または db.example.com
[PORT]	サーバーのポート。省略可能です。:[PORT] を省略すると、各データベースで通常使用されるポートが使われます
[DATABASE]	データベース名。多くの場合、省略可能です。省略して、アシスタントに一覧表示を頼むこともできます

パスワードがない場合は、:[PASSWORD] を省略します。ユーザーも指定しない場合は、[USER]:[PASSWORD]@ 全体を省略します。

MySQL と MariaDB

形式（通常のポートは3306）：

mysql://[USER]:[PASSWORD]@[HOST]:[PORT]/[DATABASE]
mariadb://[USER]:[PASSWORD]@[HOST]:[PORT]/[DATABASE]

例：

mysql://readonly:secret@localhost:3306/shop

「shop のテーブルを一覧表示してください。」 · 「orders テーブルの構造を説明してください。」 · 「先月、売上高上位10位の商品は何ですか？」

PostgreSQL

形式（通常のポートは5432）。TLS を使用するには、?sslmode=require を追加します。

postgres://[USER]:[PASSWORD]@[HOST]:[PORT]/[DATABASE]

例：

postgres://readonly:secret@localhost:5432/myapp

「reporting スキーマにはどんなテーブルがありますか？」 · 「invoices の外部キーを表示してください。」 · 「今週の日ごとの登録数を数えてください。」

SQLite

形式（スラッシュを3つ記述し、その後にファイルの完全なパスを指定します）：

sqlite:///[PATH_TO_FILE]

例：

sqlite:///Users/me/data/app.db

ファイルは読み取り専用で開かれます。

「このファイルにはどんなテーブルがありますか？」 · 「notes の先頭10行を表示してください。」

SQL Server（および Azure SQL）

形式（通常のポートは 1433）です。自己署名証明書を使用するローカルサーバーでは、?trustServerCertificate=true を追加します。

mssql://[USER]:[PASSWORD]@[HOST]:[PORT]/[DATABASE]

例：

mssql://readonly:secret@localhost:1433/Sales?trustServerCertificate=true

「Sales のテーブルを一覧表示して。」・「注文合計の多い顧客を上位 5 件表示して。」（SQL Server では LIMIT ではなく TOP 5 を使います。アシスタントは把握しています。）

ClickHouse

形式（通常のポートは 8123、clickhouse+https を使う場合は 8443）です。

clickhouse://[USER]:[PASSWORD]@[HOST]:[PORT]/[DATABASE]
clickhouse+https://[USER]:[PASSWORD]@[HOST]:[PORT]/[DATABASE]

例：

clickhouse://reader:secret@localhost:8123/analytics

「昨日は 1 時間あたり何件のイベントがありましたか？」・「events テーブルのソートキーは何ですか？」

MongoDB

形式（通常のポートは 27017）です。MongoDB Atlas では、ポートを指定せずに mongodb+srv を使います。

mongodb://[USER]:[PASSWORD]@[HOST]:[PORT]/[DATABASE]?authSource=admin
mongodb+srv://[USER]:[PASSWORD]@[CLUSTER_HOST]/[DATABASE]

例：

mongodb://reader:secret@localhost:27017/myapp?authSource=admin

「myapp にあるコレクションは何ですか？」・「users のドキュメントにはどんなフィールドがありますか？」・「100 を超える最新の注文を 5 件検索して。」・「国別にユーザー数を数えて。」

Redis（および Valkey、KeyDB）

形式（通常のポートは 6379）です。[DB_NUMBER] はデータベース番号で、省略した場合は 0 です。rediss は TLS を意味します。

redis://[USER]:[PASSWORD]@[HOST]:[PORT]/[DB_NUMBER]
rediss://[USER]:[PASSWORD]@[HOST]:[PORT]/[DB_NUMBER]

例：

redis://localhost:6379/0

「session: で始まるキーはどれですか？」・「user:42 の中身は何ですか？」・「cache:home の有効期限はあとどれくらいですか？」

Elasticsearch および OpenSearch

形式（通常のポートは 9200、データベースはありません）です。TLS では +https を追加するか、ユーザー名とパスワードの代わりに ?api_key=[API_KEY] を使います。

elasticsearch://[USER]:[PASSWORD]@[HOST]:[PORT]
opensearch://[USER]:[PASSWORD]@[HOST]:[PORT]

例：

elasticsearch+https://elastic:[email protected]:9200

「インデックスは何がありますか？」・「直近 1 時間のエラーログを検索して。」・「logs-2026.09 にはドキュメントがいくつありますか？」

読み取り専用アカウントの作成方法を含む、各データベースの詳しい説明はデータベースガイドをご覧ください。

---

複数のデータベースを使う

DB_PROFILES でそれぞれに名前を付け、質問して切り替えます（「legacy に切り替えて」「キャッシュを使って」など）。

"env": {
  "DB_PROFILES": "{\"app\": \"postgres://readonly@localhost/app\", \"legacy\": \"mysql://readonly@localhost/shop\", \"cache\": \"redis://localhost:6379/0\"}",
  "DB_DEFAULT_PROFILE": "app"
}

一覧にないデータベースにも、会話の途中で接続できます。例：「postgres://[email protected]/reports に接続して」。

特殊文字（@、/、#）を含むパスワードの場合、URL に含めず、別途指定します。DB_URL と併せて DB_PASSWORD を設定するか、DB_PROFILES 内で {"url": "...", "password": "..."} と指定してください。

---

Docker で実行する

Docker 以外にインストールするものはありません。

{
  "mcpServers": {
    "databases": {
      "command": "docker",
      "args": [
        "run", "-i", "--rm",
        "--add-host", "host.docker.internal:host-gateway",
        "-e", "DB_URL=postgres://readonly:[email protected]:5432/myapp",
        "shibbirweb/mcp-db-read-only"
      ]
    }
  }
}

Docker 内から自分のコンピューター上のデータベースに接続するには、localhost の代わりに host.docker.internal を使います。SQLite の場合は、フォルダーをマウントします。"-v", "/Users/me/data:/data:ro" を追加し、sqlite:///data/app.db を使ってください。

---

アシスタントの動作を確認する

ログを有効にすると、アシスタントが実行したすべてのクエリを記録し、ブラウザーでリアルタイムに確認できます。

flowchart LR
    S["mcp-db-read-only<br/>(in your AI client)"] -->|"one file per call"| F[("Log folder<br/>DB_LOG_DIR")]
    F --> V["viewer command<br/>(in a terminal)"]
    V -->|"live"| B["Your browser"]

1. ログをフォルダーに保存するには、サーバーの env に次の内容を追加します。

"DB_LOG_DIR": "/Users/me/Library/Logs/mcp-db-read-only"

各クエリは個別のファイルとして、日ごとのフォルダーに保存されます。自動的に削除されることはありません。

2. ビューアーを開くには、確認したいときにターミナルで次を実行します。

npx -y @shibbirweb/mcp-db-read-only viewer --dir /Users/me/Library/Logs/mcp-db-read-only --port 4800

次に http://127.0.0.1:4800/ を開きます。すべての呼び出しについて、質問内容、送信された正確なクエリ、処理時間、結果を確認できます。リアルタイムで更新され、1 ページあたり 20 件が表示されます（10、20、30、50 件から選択できます）。また、絞り込みやコピーもできます。閉じるには Ctrl+C を押してください。

ビューアーにはパスワードがありません。ネットワーク経由でこのポートにアクセスできる人は、実行中のログを読めます。

パスワードがログに記録されることはありません。詳細はログとビューアーのガイドをご覧ください。

---

本当に読み取り専用ですか？

はい。独立した2つの方法で読み取り専用にしているため、一方でミスがあっても、もう一方で検出できます。

flowchart LR
    Q["The assistant<br/>writes a query"] --> C{"1. Checked by<br/>this server:<br/>only a read?"}
    C -->|"no"| R1["Refused,<br/>with the reason"]
    C -->|"yes"| D["2. Sent to the database<br/>in read-only mode"]
    D -->|"a read"| A["The answer"]
    D -->|"a write that<br/>slipped through"| R2["Refused by<br/>the database"]

1. 何かを送信する前に、すべてのクエリをチェックします。読み取りのみが許可されます。SQL では SELECT など、Redis では読み取りコマンド、Elasticsearch では検索のみが許可され、MongoDB では $out と $merge は許可されません。
2. データベース側でも書き込みを拒否するよう設定します。対応している場合は、MySQL では読み取り専用セッション、PostgreSQL では読み取り専用トランザクション、SQLite では読み取り専用ファイルを使うなどの方法があります。

最善の保護策は、やはり読み取り専用のデータベースアカウントです。 そうすれば、何が起きてもそのアカウントでは書き込みができません。データベースガイドでは、各データベースでのアカウント作成方法を紹介しています。

アシスタントは、アカウントから見えるデータを読み取ることができ、読み取った内容は AI プロバイダーとの会話の一部になります。共有してもよいデータだけを閲覧できるアカウントを接続してください。PRIVACY.mdを参照してください。

---

設定

すべて任意です。サーバーの env に設定してください。

設定	機能
DB_URL	起動時に接続するデータベース
DB_PASSWORD	DB_URL に含めずに管理したい場合に指定するパスワード
DB_PROFILES	切り替え用の複数の名前付きデータベースを JSON で指定
DB_DEFAULT_PROFILE	起動時に使用するプロファイル
DB_QUERY_TIMEOUT_MS	指定時間後にクエリを停止します（デフォルトは 30000、つまり30秒）
DB_CONNECT_TIMEOUT_MS	指定時間後に接続を諦めます（デフォルトは 10000）
DB_LOG_DIR	すべての呼び出しをこのフォルダーにファイルとして保存
DB_LOG=true	代わりにすべての呼び出しをクライアントのログに書き込み
DB_LOG_FILE	代わりにすべての呼び出しを1つのファイルに書き込み
DB_LOG_FORMAT	DB_LOG と DB_LOG_FILE の形式。pretty（デフォルト）または json
DB_LOG_PORT	サーバー内でビューアーを実行（通常は別の viewer コマンドのほうが適しています）

mcp-mysql-read-only から移行する場合も、MYSQL_HOST、MYSQL_USER、MYSQL_PASSWORD、MYSQL_DATABASE、MYSQL_PROFILES の設定は引き続きそのまま使えます。

詳細：設定ガイド。

---

トラブルシューティング

Docker からコンピューター上のデータベースに「接続できません」。 localhost の代わりに host.docker.internal を使用し、Docker の例にある --add-host の行も残してください。

npx でサーバーが起動しません。 node --version が 22.13 以降であることを確認してください。

SQL Server で証明書が信頼されていないと表示されます。 ローカルまたは開発用サーバーの場合は、URL に ?trustServerCertificate=true を追加してください。

「データベースが選択されていません」と表示されます。 URL にデータベース名がありません。名前（.../myapp）を追加するか、アシスタントにデータベース一覧を表示させて、いずれかを選んでください。

パスワードに @ または # が含まれています。 DB_PASSWORD を使うか、DB_PROFILES で {"url": ..., "password": ...} 形式を使ってください。

ビューアーでポートが使用中と表示されます。 別のプロセスが使用しています。そのプロセスを終了するか、--port 4801 で別のポートを指定してください。

その他の回答はトラブルシューティングガイドをご覧ください。

---

詳細情報

• Wiki：すべての機能に関するユーザーガイドと開発者向けドキュメント
• CHANGELOG.md：各バージョンでの変更点
• PRIVACY.md：サーバーがどこに何を送信するか（お使いのデータベース以外には何も送信しません）
• 貢献：master へのプルリクエストを歓迎します。./scripts/test-in-docker.sh を実行すると、使い捨てコンテナー内で各データベースを対象にテストスイート全体を実行できます。テストを参照してください。この README を変更した場合は、README.dockerhub.md も合わせて変更してください。

ライセンス

MIT © Md. Shibbir Ahmed