shibbirweb/mcp-db-read-only repository overview

⁠mcp-db-read-only

Let your AI assistant look at your databases without being able to change them.

Point it at MySQL, PostgreSQL, SQLite, SQL Server, ClickHouse, MongoDB, Redis or Elasticsearch, then just ask questions in plain words: "how many users signed up this week?", "what's in the orders table?", "which Redis keys hold sessions?". It can read anything you give it access to, and it cannot write, update or delete anything.

• Every popular database, one server. Switch between them in the middle of a conversation.
• Read-only, twice over. Every query is checked before it is sent, and the database itself is also told to refuse writes.
• No restart to switch. Change database, server or engine by asking.
• Optional logging, with a live page in your browser that shows every query as it happens.

You  --ask in plain words-->  Your AI assistant  --tool call-->  mcp-db-read-only  --read-only query-->  Your databases
                                                                  mcp-db-read-only  <--rows, documents, keys--

Works with Claude Desktop, Claude Code, and any other MCP⁠ client.

Source and full documentation: github.com/shibbirweb/mcp-db-read-only⁠

⁠Supported tags

1.1.0, 1.1, 1, latest, built for linux/amd64 and linux/arm64.

⁠Quick start

1. Have Node.js 22.13 or newer (node --version), or Docker.

2. Add the server to your client. For Claude Desktop, edit claude_desktop_config.json (Settings, Developer, Edit Config). For Claude Code, create .mcp.json in your project:

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

Replace the DB_URL with your own database. The examples below show one for every kind.

3. Restart the client once, and ask away:

That's it. You never need to restart again to change database; just ask the assistant to switch.

⁠Examples for each database

Each database has a URL format, then a real example to copy and change. Put the finished URL in DB_URL.

Replace each [PLACEHOLDER] with your own value:

No password? Leave out :[PASSWORD]. No user either? Leave out [USER]:[PASSWORD]@ entirely.

⁠MySQL and MariaDB

Format (usual port 3306):

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

Example:

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

⁠PostgreSQL

Format (usual port 5432). Add ?sslmode=require to use TLS:

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

Example:

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

⁠SQLite

Format (three slashes, then the full path to the file):

sqlite:///[PATH_TO_FILE]

Example:

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

The file is opened read-only.

⁠SQL Server (and Azure SQL)

Format (usual port 1433). Add ?trustServerCertificate=true for a local server with a self-signed certificate:

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

Example:

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

⁠ClickHouse

Format (usual port 8123, or 8443 with clickhouse+https):

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

Example:

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

⁠MongoDB

Format (usual port 27017). Use mongodb+srv for MongoDB Atlas, with no port:

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

Example:

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

⁠Redis (and Valkey, KeyDB)

Format (usual port 6379). [DB_NUMBER] is the database number, 0 if left out; rediss means TLS:

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

Example:

redis://localhost:6379/0

⁠Elasticsearch and OpenSearch

Format (usual port 9200, no database). Add +https for TLS, or ?api_key=[API_KEY] instead of a user and password:

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

Example:

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

Detailed notes for every database, including how to create a read-only account, are in the Databases guide⁠.

⁠Using several databases

Give each one a name with DB_PROFILES, and switch by asking ("switch to legacy", "use the cache"):

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

You can also connect to a database you didn't list, mid-conversation: "connect to postgres://[email protected]/reports".

Password with special characters (@, /, #)? Give it separately instead of inside the URL: DB_PASSWORD next to DB_URL, or {"url": "...", "password": "..."} inside DB_PROFILES.

⁠Running with Docker

Nothing to install but 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"
      ]
    }
  }
}

Inside Docker, use host.docker.internal instead of localhost to reach a database on your own computer. For SQLite, mount the folder: add "-v", "/Users/me/data:/data:ro" and use sqlite:///data/app.db.

⁠Watching what the assistant does

Turn on logging to keep a record of every query the assistant runs, and see them live in your browser.

The assistant writes a query
             |
             v
1. Checked by this server: only a read?
     no  -->  Refused, with the reason
     yes -->  2. Sent to the database in read-only mode
                   a read                         -->  The answer
                   a write that slipped through   -->  Refused by the database

1. Save logs to a folder by adding this to the server's env:

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

Each query is saved as its own file, one folder per day. Nothing is ever deleted automatically.

2. Open the viewer in a terminal, whenever you want to watch:

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

Then open http://127.0.0.1:4800/⁠. You'll see every call: what was asked, the exact query sent, how long it took, and the result. It updates live, shows 20 per page (10, 20, 30 or 50 to choose from), and lets you filter and copy anything. Press Ctrl+C to close it.

Passwords are never written to the logs. More in the Logging guide⁠.

⁠Is it really read-only?

Yes, in two independent ways, so a mistake in one is caught by the other:

mcp-db-read-only  --one file per call-->  Log folder (DB_LOG_DIR)  -->  viewer command  --live-->  Your browser
(in your AI client)                                                     (in a terminal)

1. Before anything is sent, every query is checked. Only reads are allowed: SELECT and friends for SQL, read commands for Redis, searches for Elasticsearch, and no $out or $merge for MongoDB.
2. The database is told to refuse writes too, wherever it supports that: read-only sessions on MySQL, read-only transactions on PostgreSQL, a read-only file on SQLite, and so on.

The best protection is still a read-only database account. Then nothing can write through it, whatever happens. The Databases guide⁠ shows how to create one for each database.

Keep in mind that the assistant can read whatever the account can see, and what it reads becomes part of your conversation with the AI provider. Only connect accounts that can see data you are happy to share. See PRIVACY.md⁠.

⁠Settings

All optional. Set them in the server's env.

Coming from mcp-mysql-read-only? Its MYSQL_HOST, MYSQL_USER, MYSQL_PASSWORD, MYSQL_DATABASE and MYSQL_PROFILES settings still work as they are.

Full details: Configuration guide⁠.

⁠Troubleshooting

"Can't connect" from Docker to a database on my computer. Use host.docker.internal instead of localhost, and keep the --add-host line from the Docker example.

The server won't start with npx. Check node --version is 22.13 or newer.

SQL Server says the certificate isn't trusted. Add ?trustServerCertificate=true to the URL for a local or development server.

"No database selected". Your URL has no database name. Add one (.../myapp), or ask the assistant to list the databases and pick one.

My password has @ or # in it. Use DB_PASSWORD, or the {"url": ..., "password": ...} form in DB_PROFILES.

The viewer says the port is in use. Something else is using it. Close that, or pick another port with --port 4801.

More answers in the Troubleshooting guide⁠.

⁠Learn more

• Wiki⁠: user guides for every feature, plus developer documentation
• CHANGELOG.md⁠: what changed in each version
• PRIVACY.md⁠: what the server sends where (nothing, except to your databases)
• Contributing: pull requests to master are welcome. ./scripts/test-in-docker.sh runs the full test suite against every database in throwaway containers; see Testing⁠. If you change this README, change README.dockerhub.md⁠ to match.

⁠License

MIT⁠ © Md. Shibbir Ahmed