Databases (read-only, switchable)

mcp-db-read-only

让你的 AI 助手查看数据库，但无法修改数据。

将其连接到 MySQL、PostgreSQL、SQLite、SQL Server、ClickHouse、MongoDB、Redis 或 Elasticsearch，然后用日常语言提问即可：“本周有多少用户注册？”、“orders 表里有什么？”、“哪些 Redis 键存储了会话？”。它可以读取你授权访问的所有内容，但无法写入、更新或删除任何数据。

• 一个服务支持所有常见数据库。 在对话过程中即可切换。
• 双重只读保护。 每条查询都会在发送前经过检查，数据库本身也会被要求拒绝写入。
• 无需重启即可切换。 只需提出请求，即可更换数据库、服务器或引擎。
• 可选日志记录，并在浏览器中提供实时页面，展示每条查询的执行情况。

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. 将服务添加到客户端。 对于 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 替换为你自己的数据库连接。下面的示例展示了每种数据库的配置。

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）。添加 ?sslmode=require 以使用 TLS：

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

示例：

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

“reporting 架构中有哪些表？” · “显示 invoices 上的外键。” · “统计本周每天的注册数。”

SQLite

格式（三个斜杠，后接文件的完整路径）：

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 使用 TOP 5，而不是 LIMIT；助手知道这一点。）

ClickHouse

格式（通常使用端口 8123，或使用 clickhouse+https 时为 8443）：

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

示例：

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

“昨天每小时有多少个事件？” · “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 中的文档有哪些字段？” · “查找最近的 5 个金额超过 100 的订单。” · “按国家统计用户数。”

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，不指定数据库）。使用 +https 启用 TLS，或使用 ?api_key=[API_KEY] 代替用户名和密码：

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

示例：

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

“我们有哪些索引？” · “查找过去一小时的错误日志。” · “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 中，使用 host.docker.internal 而不是 localhost 来访问自己电脑上的数据库。对于 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/**。你会看到每次调用的详细信息：用户提出的问题、发送的确切查询、耗时和结果。查看器会实时更新，每页显示 20 条（可选择 10、20、30 或 50 条），并支持筛选和复制内容。按 Ctrl+C 关闭。

查看器没有密码。运行期间，网络上任何能够访问该端口的人都可以读取日志。

密码绝不会写入日志。更多信息请参阅日志指南。

---

它真的只读吗？

是的，通过两种相互独立的方式实现，因此其中一种出错时，另一种也能拦截：

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 的密码，如果你不想将密码放在 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	将每次调用写入同一个文件
DB_LOG_FORMAT	pretty（默认值）或 json，适用于 DB_LOG 和 DB_LOG_FILE
DB_LOG_PORT	在服务内部运行查看器（通常单独使用 viewer 命令更好）

从 mcp-mysql-read-only 迁移而来？其 MYSQL_HOST、MYSQL_USER、MYSQL_PASSWORD、MYSQL_DATABASE 和 MYSQL_PROFILES 设置仍可照常使用。

完整详情请参阅：配置指南。

---

故障排除

Docker 无法连接到我电脑上的数据库。 使用 host.docker.internal 代替 localhost，并保留 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