Custom Database MCP server

Custom MCP Database

<!-- MCP Registry ownership proof — required to publish to registry.modelcontextprotocol.io --> mcp-name: io.github.renanlido/custom-mcp-database

An MCP server that lets AI agents run alias-based queries against PostgreSQL, MySQL, MongoDB and Oracle — without ever exposing credentials to the model. Connections are configured once and stored locally; the agent only ever references them by alias.

Works with Claude Code, Claude Desktop, Cursor, VS Code, Windsurf, Gemini CLI, and any other MCP client (all use the same stdio launch command).

Quickstart

There are two roles, on purpose. Keeping them separate is what stops your DB password from ever reaching the model.

You (once, in your terminal) — install the credentials

The agent never installs credentials. You do, with the CLI. The secret stays on your machine and is never sent to the model.

Easiest way — the guided wizard (asks type, host, user, and how to supply the secret; optionally tests the connection):

uvx custom-mcp-database setup

Or do it in one line (you'll be prompted for the password — hidden input):

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

The agent (always) — uses it by alias

Point your MCP client at the server (see Install), then just ask:

"Using prodro, run SELECT count() FROM orders."

The agent calls dbexecutequery with the alias prod_ro — never a host, user, or password. It physically cannot see the credentials; they live in your local config, resolved only inside the server process at query time.

Why the agent can't add the DB: an MCP tool's arguments are produced and read by the LLM. If the agent typed your password into an add tool, that password would land in the model's context, the provider, and the logs. So credential setup is a human/CLI step by design. (Need an agent to wire connections in an automated pipeline? See MCPDBALLOWADMINTOOLS in SECURITY.md — even then it only accepts a reference to a secret, e.g. an env-var name, never the secret itself.)

Writes are off by default (read-only). To allow them for a task: export MCPDBREADONLY=0 MCPDBALLOW_WRITES=1.

Install

The server runs over stdio. The universal launch command is uvx custom-mcp-database run (requires uv; the package is fetched from PyPI on first run).

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

Two options:

1. One-click bundle — build the .mcpb (mcpb pack) and open it in Claude Desktop. See Distribution.
2. Manual config — add the snippet from examples/mcp-clients/claude-desktop.json to claudedesktopconfig.json.

Other clients

Copy the matching snippet — all use the same command/args, only the file and key differ:

Full client matrix and a local-checkout variant: examples/mcp-clients/README.md.

Configure connections

Shortened. The full README is on GitHub.