custom-mcp-database

カスタム MCP データベース

mcp-name: io.github.renanlido/custom-mcp-database

AI エージェントが PostgreSQL、MySQL、MongoDB、Oracle に対してエイリアスベースの クエリを実行できる MCP サーバーです。モデルに認証情報が公開されることはありません。接続は一度設定してローカルに保存し、エージェントは常にエイリアスで接続を参照します。

Claude Code、Claude Desktop、Cursor、VS Code、Windsurf、Gemini CLI、その他の MCP クライアントに対応しています（すべて同じ stdio 起動コマンドを使用します）。

---

クイックスタート

意図的に2つの役割を設けています。役割を分けることで、DB のパスワードがモデルに渡るのを防ぎます。

あなた（ターミナルで一度だけ）— 認証情報をインストールします

エージェントが認証情報をインストールすることはありません。 インストールするのは CLI を使うあなたです。シークレットはあなたのマシンに保存され、モデルに送信されることはありません。

最も簡単な方法は、ガイド付きウィザードを使うことです（種類、ホスト、ユーザー、シークレットの指定方法を尋ねます。オプションで接続をテストできます）。

uvx custom-mcp-database setup

または、1行で実行します（パスワードの入力が求められます。入力内容は表示されません）。

uvx custom-mcp-database add-db --alias prod_ro --type postgres \
  --host db.internal --port 5432 --user reporting --dbname app

uvx custom-mcp-database list-aliases   # confirm it's there

エージェント（常時）— エイリアスで使用します

MCP クライアントをサーバーに接続し（インストールを参照）、次のように依頼します。

「prod_ro を使って、SELECT count(*) FROM orders を実行してください。」

エージェントはエイリアス prod_ro を指定して db_execute_query を呼び出します。ホスト、ユーザー、パスワードを指定することはありません。エージェントが認証情報を参照することは物理的に不可能です。認証情報はローカル設定に保存され、クエリ実行時にサーバープロセス内でのみ解決されます。

エージェントが DB を追加できない理由： MCP ツールの引数は LLM が生成して読み取ります。エージェントが add ツールにパスワードを入力すると、そのパスワードはモデルのコンテキスト、プロバイダー、ログに記録されてしまいます。そのため、認証情報の設定は設計上、人が CLI で行う手順になっています。（自動化されたパイプラインでエージェントに接続を設定させる必要がある場合は、SECURITY.md の MCP_DB_ALLOW_ADMIN_TOOLS を参照してください。それでも、受け付けるのは環境変数名などのシークレットへの参照のみで、シークレットそのものは受け付けません。）

書き込みはデフォルトで無効（読み取り専用）です。特定のタスクで許可するには、次を実行します。 export MCP_DB_READONLY=0 MCP_DB_ALLOW_WRITES=1

---

インストール

サーバーは stdio 経由で実行します。共通の起動コマンドは uvx custom-mcp-database run です（uv が必要です。初回実行時にパッケージが PyPI から取得されます）。

Claude Code

# Direct (published package)
claude mcp add custom-mcp-database -- uvx custom-mcp-database run

# Or install the full plugin from this repo's marketplace
/plugin marketplace add renanlido/custom-mcp-database
/plugin install custom-mcp-database@renanlido-mcp

Claude Desktop

方法は2つあります。

1. ワンクリックバンドル — .mcpb を作成し（mcpb pack）、Claude Desktop で開きます。配布を参照してください。
2. 手動設定 — examples/mcp-clients/claude-desktop.json のスニペットを claude_desktop_config.json に追加します。

その他のクライアント

該当するスニペットをコピーします。すべて同じ command／args を使用し、ファイルとキーのみが異なります。

クライアント	設定ファイル	キー	スニペット
Cursor	~/.cursor/mcp.json	mcpServers	cursor.json
VS Code	.vscode/mcp.json	servers	vscode.json
Windsurf	~/.codeium/windsurf/mcp_config.json	mcpServers	windsurf.json
Gemini CLI	~/.gemini/settings.json	mcpServers	gemini-cli.json

すべてのクライアントの一覧と、ローカルチェックアウトを使う場合の手順については、examples/mcp-clients/README.mdを参照してください。

---

接続を設定する

エージェント経由ではなく、ターミナルから CLI で接続を設定してください。 接続のパスワードは実際の秘密情報です。MCP ツールの引数として渡すと、モデルのコンテキスト（およびプロバイダー、トランスクリプト、ログ）に含まれてしまいます。そのため、認証情報管理ツールはデフォルトで MCP の公開対象外です。接続の設定は人間が CLI で行う作業です。エージェントはエイリアスの一覧表示と使用のみを行います。

--password／--uri を省略すると、安全に入力するよう求められます（入力は非表示で、シェル履歴には保存されません）。さらに、--password-env／--password-file を使えば、接続時に解決されるため、設定ファイルから秘密情報を完全に除外できます。

# PostgreSQL — prompted for the password (recommended)
uvx custom-mcp-database add-db --alias pg --type postgres \
  --host localhost --port 5432 --user me --dbname app

# MySQL — password taken from an env var at connect time (nothing secret on disk)
MYSQL_PW=... uvx custom-mcp-database add-db --alias my --type mysql \
  --host localhost --port 3306 --user root --dbname app --password-env MYSQL_PW

# Oracle — password read from a file (e.g. a mounted secret)
uvx custom-mcp-database add-db --alias ora --type oracle \
  --host db.example.com --port 1521 --user system --dbname ORCLPDB1 \
  --password-file /run/secrets/ora_pw

# MongoDB — full URI from a file (the URI embeds credentials)
uvx custom-mcp-database add-db --alias mongo --type mongo \
  --dbname app --uri-file /run/secrets/mongo_uri

uvx custom-mcp-database list-aliases
uvx custom-mcp-database remove-db --alias pg

設定ファイルの場所（MCP_DB_CONFIG で上書き可能）： $XDG_CONFIG_HOME/custom-mcp-database/mcp_config.sqlite3 （デフォルトは ~/.config/custom-mcp-database/mcp_config.sqlite3、権限は 0600）。

--password／--uri にリテラル値を渡すと、その値は SQLite ファイルにプレーンテキストの JSONとして保存されます。参照のみを保存するため、--password-env／--password-file（または --uri-env／--uri-file）を使用してください。いずれの場合も、ファイルは秘密にしておいてください（権限は 0600 で、gitignore 対象ですが、暗号化されていません）。

---

MCP ツール

ツール	目的
db_list_aliases	設定済みのエイリアスと種類を一覧表示します
db_execute_query	SQL または MongoDB の JSON フィルターを実行します
db_list_collections	MongoDB のコレクションを一覧表示します
db_security_status	有効なセキュリティポリシーを報告します

db_add_database／db_remove_database は、デフォルトでは MCP 経由で公開されません。接続は CLI で管理してください。これらの公開を有効にするには（追加ツールで受け付ける秘密情報は参照のみで、パスワードのリテラル値は受け付けません）、MCP_DB_ALLOW_ADMIN_TOOLS=1 を設定します。

db_execute_query に関する注意事項：SQL は指定どおりにパラメーター化バインドで実行されます（LIMIT は自分で追加してください）。MongoDB は JSON フィルターと collection を受け取り、結果を 10 件までに制限し（--limit）、空のフィルターを拒否して、24 文字の 16 進数文字列を ObjectId に変換します。

---

セキュリティ

このサーバーは実際の認証情報と本番データを扱うため、デフォルトで拒否するように設計されています。

• デフォルトは読み取り専用です。 SELECT 系の SQL のみ実行されます。書き込み／DDL には明示的なオプトインが必要です。
• 複数ステートメントは禁止です（; によるインジェクションをブロック）。1 回の呼び出しにつき 1 つのステートメントのみ実行されます。
• MongoDB サーバーサイド JavaScript はブロックされます（$where、$function、$accumulator、mapReduce など）。
• 識別子は検証されます（oracle_schema をインジェクションに使用することはできません）。
• 結果は MCP_DB_MAX_ROWS（デフォルトは 1000 件）までに制限されます。 エラーから秘密情報は伏せられます。
• 認証情報ストアは 0600 のプレーンテキスト SQLite です。ホストのディスクを暗号化してください。

現在のセキュリティ状態を確認するには、custom-mcp-database security-status（または db_security_status ツール）を実行します。

特定のタスクで書き込みを有効にし、完了後に無効に戻します。

export MCP_DB_READONLY=0
export MCP_DB_ALLOW_WRITES=1     # INSERT/UPDATE/DELETE
# export MCP_DB_ALLOW_DDL=1      # only if you really need CREATE/DROP/ALTER/...

最小権限の DB ロール、TLS、プロンプトインジェクションへの対処、脆弱性の報告については、SECURITY.md でプロトコル全文をお読みください。 アプリケーション層のガードは多層防御の一部です。最も重要な制御は、最小権限のデータベースアカウントです。

開発

uv sync                 # create .venv and install deps
make run                # run the server (stdio)
make lint               # ruff
make build              # sdist + wheel into dist/

ツールを対話的に調べます。

uv run mcp dev src/custom_mcp_database/server.py

---

配布

このリポジトリには、主要な各配布チャネル向けに、公開準備が整ったメタデータが用意されています。すべて main への push 時に自動で公開されます（下記参照）。

チャネル	ファイル	公開方法
PyPI	pyproject.toml	release.yml（main への push）
MCP Registry	server.json	release.yml（main への push）
Claude Code プラグイン	.claude-plugin/plugin.json、.mcp.json	GitHub への push で利用可能
Claude Code マーケットプレイス	.claude-plugin/marketplace.json	GitHub への push で利用可能
Claude Desktop バンドル	manifest.json	release.yml が .mcpb を Release に添付

自動リリース — main にプッシュするだけ

リリースはすべて自動化されています。main にプッシュするたびに、 .github/workflows/release.yml が次の処理を行います。

1. 最後のタグ以降のコミットから、次のセマンティックバージョンを選択します （feat: → マイナー、BREAKING CHANGE／type!: → メジャー、それ以外 → パッチ。 スキップするには、コミットメッセージに [skip release] を追加します）。
2. そのバージョンを pyproject.toml に書き込み、scripts/sync_version.py を使って すべての成果物（server.json、manifest.json、プラグイン＋マーケットプレイス）に同期します — バージョンは1か所で管理し、手動で更新する必要はありません。
3. ビルドし、chore(release): vX [skip ci] をコミットして、vX のタグを付け、プッシュします。
4. PyPI（Trusted Publishing／OIDC）に公開してから、MCP Registry（GitHub OIDC）に公開します。
5. .mcpb をパッケージ化し、wheel とバンドルを添付した GitHub Release を作成します。

リリースコミットには [skip ci] が含まれるため、ワークフローは再実行されません。

初回のみの設定（自動化できません — アカウントが必要です）：

• renanlido/custom-mcp-database 用に、ワークフロー release.yml の PyPI Trusted Publisher を作成します。
• GitHub Actions に main へのプッシュを許可します（リポジトリ → Settings → Actions → Read and write permissions。main が保護ブランチの場合は、actions bot にバイパスを許可するか、PAT を使用します）。

MCP Registry の名前空間は io.github.renanlido/custom-mcp-database です（GitHub による検証済み）。

ローカルでの手動実行方法：make build（バージョンを同期してビルド）を実行し、その後 uv publish を実行します。

---

ライセンス

MIT