@shibbirweb/mcp-db-read-only 0.2.0 → 1.1.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/CHANGELOG.md +16 -0
- package/README.dockerhub.md +234 -289
- package/README.md +221 -320
- package/dist/cli/ViewerCommand.js +117 -0
- package/dist/index.js +16 -7
- package/dist/logging/viewer/LiveLogViewer.js +8 -0
- package/dist/logging/viewer/ViewerAssets.js +26 -0
- package/package.json +1 -1
package/README.md
CHANGED
|
@@ -2,81 +2,37 @@
|
|
|
2
2
|
|
|
3
3
|
[](https://github.com/shibbirweb/mcp-db-read-only/actions/workflows/ci.yml)
|
|
4
4
|
[](https://www.npmjs.com/package/@shibbirweb/mcp-db-read-only)
|
|
5
|
+
[](https://www.npmjs.com/package/@shibbirweb/mcp-db-read-only)
|
|
5
6
|
[](https://hub.docker.com/r/shibbirweb/mcp-db-read-only)
|
|
6
|
-
[](https://hub.docker.com/r/shibbirweb/mcp-db-read-only)
|
|
7
8
|
[](LICENSE)
|
|
8
9
|
|
|
9
|
-
|
|
10
|
+
Let your AI assistant **look at your databases without being able to change them.**
|
|
10
11
|
|
|
11
|
-
|
|
12
|
-
| --- | --- | --- |
|
|
13
|
-
| MySQL, MariaDB | `mysql://`, `mariadb://` | `run_query` (SQL) |
|
|
14
|
-
| PostgreSQL (and wire-compatible) | `postgres://`, `postgresql://` | `run_query` (SQL) |
|
|
15
|
-
| SQLite | `sqlite:///path/to/file.db` | `run_query` (SQL) |
|
|
16
|
-
| SQL Server, Azure SQL | `mssql://`, `sqlserver://` | `run_query` (T-SQL) |
|
|
17
|
-
| ClickHouse | `clickhouse://`, `clickhouse+https://` | `run_query` (SQL) |
|
|
18
|
-
| MongoDB | `mongodb://`, `mongodb+srv://` | `find_documents`, `aggregate`, `count_documents`, `distinct_values` |
|
|
19
|
-
| Redis (and Valkey, KeyDB) | `redis://`, `rediss://` | `redis_command` |
|
|
20
|
-
| Elasticsearch, OpenSearch | `elasticsearch://`, `opensearch://`, `+https` variants | `search` |
|
|
12
|
+
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.
|
|
21
13
|
|
|
22
|
-
|
|
23
|
-
|
|
24
|
-
|
|
14
|
+
- **Every popular database, one server.** Switch between them in the middle of a conversation.
|
|
15
|
+
- **Read-only, twice over.** Every query is checked before it is sent, and the database itself is also told to refuse writes.
|
|
16
|
+
- **No restart to switch.** Change database, server or engine by asking.
|
|
17
|
+
- **Optional logging**, with a live page in your browser that shows every query as it happens.
|
|
25
18
|
|
|
26
19
|
```mermaid
|
|
27
20
|
flowchart LR
|
|
28
|
-
|
|
29
|
-
|
|
30
|
-
|
|
31
|
-
|
|
32
|
-
E[("MongoDB<br/>events")]
|
|
33
|
-
F[("Redis<br/>cache")]
|
|
34
|
-
G[("anything reached<br/>with connect")]
|
|
35
|
-
|
|
36
|
-
A <-->|"MCP over stdio"| B
|
|
37
|
-
B -.->|"one driver per target"| C
|
|
38
|
-
B -.->|"one driver per target"| D
|
|
39
|
-
B -.->|"one driver per target"| E
|
|
40
|
-
B -.->|"one driver per target"| F
|
|
41
|
-
B -.->|"opened at runtime"| G
|
|
21
|
+
Y["You"] -->|"ask in plain words"| AI["Your AI assistant"]
|
|
22
|
+
AI -->|"tool call"| S["mcp-db-read-only"]
|
|
23
|
+
S -->|"read-only query"| DB[("Your databases")]
|
|
24
|
+
DB -->|"rows, documents, keys"| S
|
|
42
25
|
```
|
|
43
26
|
|
|
44
|
-
|
|
27
|
+
Works with Claude Desktop, Claude Code, and any other [MCP](https://modelcontextprotocol.io) client.
|
|
45
28
|
|
|
46
29
|
---
|
|
47
30
|
|
|
48
31
|
## Quick start
|
|
49
32
|
|
|
50
|
-
|
|
51
|
-
|
|
52
|
-
```bash
|
|
53
|
-
DB_URL='postgres://readonly:secret@127.0.0.1:5432/my_database' npx -y @shibbirweb/mcp-db-read-only
|
|
54
|
-
```
|
|
55
|
-
|
|
56
|
-
Requires Node 22.13 or newer. There is no container in the way, so `127.0.0.1` means what you expect.
|
|
57
|
-
|
|
58
|
-
### Docker
|
|
59
|
-
|
|
60
|
-
```bash
|
|
61
|
-
docker run -i --rm \
|
|
62
|
-
--add-host host.docker.internal:host-gateway \
|
|
63
|
-
-e DB_URL='postgres://readonly:secret@host.docker.internal:5432/my_database' \
|
|
64
|
-
shibbirweb/mcp-db-read-only
|
|
65
|
-
```
|
|
66
|
-
|
|
67
|
-
Use `host.docker.internal` to reach a database on the same machine as Docker. Inside the container, `localhost` means the container itself.
|
|
68
|
-
|
|
69
|
-
For SQLite in Docker, mount the file's directory read-only and point at the path inside the container:
|
|
70
|
-
|
|
71
|
-
```bash
|
|
72
|
-
docker run -i --rm -v "$PWD/data:/data:ro" -e DB_URL='sqlite:///data/app.db' shibbirweb/mcp-db-read-only
|
|
73
|
-
```
|
|
74
|
-
|
|
75
|
-
The container is the more isolated of the two: the server runs with only what the image and the environment give it. Over npm it runs directly on your machine with your user's access. Both enforce the same read-only guarantees.
|
|
33
|
+
**1. Have Node.js 22.13 or newer** (`node --version`), or Docker.
|
|
76
34
|
|
|
77
|
-
|
|
78
|
-
|
|
79
|
-
Add to `claude_desktop_config.json`:
|
|
35
|
+
**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:
|
|
80
36
|
|
|
81
37
|
```json
|
|
82
38
|
{
|
|
@@ -85,379 +41,324 @@ Add to `claude_desktop_config.json`:
|
|
|
85
41
|
"command": "npx",
|
|
86
42
|
"args": ["-y", "@shibbirweb/mcp-db-read-only"],
|
|
87
43
|
"env": {
|
|
88
|
-
"
|
|
89
|
-
"DB_DEFAULT_PROFILE": "app"
|
|
44
|
+
"DB_URL": "postgres://readonly:secret@localhost:5432/myapp"
|
|
90
45
|
}
|
|
91
46
|
}
|
|
92
47
|
}
|
|
93
48
|
}
|
|
94
49
|
```
|
|
95
50
|
|
|
96
|
-
|
|
51
|
+
Replace the `DB_URL` with your own database. The examples below show one for every kind.
|
|
97
52
|
|
|
98
|
-
|
|
99
|
-
{
|
|
100
|
-
"mcpServers": {
|
|
101
|
-
"databases": {
|
|
102
|
-
"command": "docker",
|
|
103
|
-
"args": [
|
|
104
|
-
"run", "-i", "--rm",
|
|
105
|
-
"--add-host", "host.docker.internal:host-gateway",
|
|
106
|
-
"-e", "DB_URL=postgres://readonly:secret@host.docker.internal:5432/app",
|
|
107
|
-
"shibbirweb/mcp-db-read-only"
|
|
108
|
-
]
|
|
109
|
-
}
|
|
110
|
-
}
|
|
111
|
-
}
|
|
112
|
-
```
|
|
53
|
+
**3. Restart the client once, and ask away:**
|
|
113
54
|
|
|
114
|
-
|
|
55
|
+
> "What tables are in my database?"
|
|
56
|
+
> "Show me the 5 newest orders."
|
|
57
|
+
> "How many customers are in each country?"
|
|
115
58
|
|
|
116
|
-
|
|
59
|
+
That's it. You never need to restart again to change database; just ask the assistant to switch.
|
|
117
60
|
|
|
118
|
-
|
|
61
|
+
---
|
|
119
62
|
|
|
120
|
-
|
|
63
|
+
## Examples for each database
|
|
121
64
|
|
|
122
|
-
|
|
65
|
+
Each database has a URL **format**, then a real **example** to copy and change. Put the finished URL in `DB_URL`.
|
|
123
66
|
|
|
124
|
-
|
|
67
|
+
Replace each `[PLACEHOLDER]` with your own value:
|
|
125
68
|
|
|
126
|
-
|
|
69
|
+
| Placeholder | What to put there |
|
|
70
|
+
| --- | --- |
|
|
71
|
+
| `[USER]` | The database user name |
|
|
72
|
+
| `[PASSWORD]` | That user's password |
|
|
73
|
+
| `[HOST]` | The server's address, e.g. `localhost` or `db.example.com` |
|
|
74
|
+
| `[PORT]` | The server's port. Optional: leave out `:[PORT]` to use the usual one shown for each database |
|
|
75
|
+
| `[DATABASE]` | The database name. Optional for most: leave it out and ask the assistant to list them |
|
|
127
76
|
|
|
128
|
-
|
|
77
|
+
No password? Leave out `:[PASSWORD]`. No user either? Leave out `[USER]:[PASSWORD]@` entirely.
|
|
129
78
|
|
|
130
|
-
|
|
79
|
+
### MySQL and MariaDB
|
|
131
80
|
|
|
132
|
-
|
|
133
|
-
> "what collections are in the events database?"
|
|
134
|
-
> "connect to the Redis on 10.0.0.5 and show me the session keys"
|
|
81
|
+
Format (usual port 3306):
|
|
135
82
|
|
|
136
|
-
|
|
137
|
-
|
|
138
|
-
|
|
139
|
-
|
|
140
|
-
| A different server, credentials or engine | No |
|
|
141
|
-
| A new permanent profile in `DB_PROFILES` | Yes, once |
|
|
83
|
+
```text
|
|
84
|
+
mysql://[USER]:[PASSWORD]@[HOST]:[PORT]/[DATABASE]
|
|
85
|
+
mariadb://[USER]:[PASSWORD]@[HOST]:[PORT]/[DATABASE]
|
|
86
|
+
```
|
|
142
87
|
|
|
143
|
-
|
|
144
|
-
|
|
145
|
-
|
|
146
|
-
|
|
147
|
-
participant A as Assistant
|
|
148
|
-
participant S as MCP server
|
|
149
|
-
participant P as PostgreSQL
|
|
150
|
-
participant M as MongoDB
|
|
151
|
-
|
|
152
|
-
You->>A: "how many signups yesterday?"
|
|
153
|
-
A->>S: run_query(SELECT count(*) ...)
|
|
154
|
-
S->>P: read-only transaction
|
|
155
|
-
P-->>S: 4821
|
|
156
|
-
A-->>You: 4821 signups
|
|
157
|
-
|
|
158
|
-
You->>A: "and how many of them opened the app?"
|
|
159
|
-
A->>S: use_connection(events)
|
|
160
|
-
S->>M: connect + ping
|
|
161
|
-
Note over S: verified, so the switch is committed
|
|
162
|
-
A->>S: count_documents(opens, {...})
|
|
163
|
-
S->>M: countDocuments
|
|
164
|
-
M-->>S: 3907
|
|
165
|
-
A-->>You: 3907 of them
|
|
88
|
+
Example:
|
|
89
|
+
|
|
90
|
+
```text
|
|
91
|
+
mysql://readonly:secret@localhost:3306/shop
|
|
166
92
|
```
|
|
167
93
|
|
|
168
|
-
|
|
94
|
+
> "List the tables in shop." · "Describe the orders table." · "What were last month's top 10 products by revenue?"
|
|
169
95
|
|
|
170
|
-
###
|
|
96
|
+
### PostgreSQL
|
|
171
97
|
|
|
172
|
-
|
|
98
|
+
Format (usual port 5432). Add `?sslmode=require` to use TLS:
|
|
173
99
|
|
|
174
|
-
```
|
|
175
|
-
|
|
176
|
-
"app": "postgres://readonly@db.internal:5432/app",
|
|
177
|
-
"legacy": "mysql://readonly@legacy.internal/shop",
|
|
178
|
-
"events": { "url": "mongodb://reader@mongo.internal/events", "password": "p@ss/w#rd" },
|
|
179
|
-
"cache": "redis://cache.internal:6379/0",
|
|
180
|
-
"logs": "elasticsearch+https://reader@logs.internal:9200",
|
|
181
|
-
"reports": "sqlite:///data/reports.db"
|
|
182
|
-
}
|
|
100
|
+
```text
|
|
101
|
+
postgres://[USER]:[PASSWORD]@[HOST]:[PORT]/[DATABASE]
|
|
183
102
|
```
|
|
184
103
|
|
|
185
|
-
|
|
104
|
+
Example:
|
|
186
105
|
|
|
187
|
-
|
|
106
|
+
```text
|
|
107
|
+
postgres://readonly:secret@localhost:5432/myapp
|
|
108
|
+
```
|
|
188
109
|
|
|
189
|
-
|
|
110
|
+
> "Which tables are in the reporting schema?" · "Show the foreign keys on invoices." · "Count signups per day this week."
|
|
190
111
|
|
|
191
|
-
###
|
|
112
|
+
### SQLite
|
|
192
113
|
|
|
193
|
-
|
|
194
|
-
| --- | --- |
|
|
195
|
-
| MySQL | `?ssl=true` requires TLS; `?ssl-mode=VERIFY_IDENTITY` also checks the certificate |
|
|
196
|
-
| PostgreSQL | `?sslmode=require`, `verify-ca` or `verify-full`, as in libpq |
|
|
197
|
-
| SQLite | `sqlite:///absolute/path.db`; a relative path is resolved once, at startup |
|
|
198
|
-
| SQL Server | Encrypted by default. `?trustServerCertificate=true` for self-signed development servers; `?applicationIntent=ReadOnly` routes to a readable secondary |
|
|
199
|
-
| ClickHouse | The HTTP interface: port 8123, or 8443 with `clickhouse+https` |
|
|
200
|
-
| MongoDB | Replica sets as `mongodb://a:27017,b:27017/db?replicaSet=rs0`; any driver option passes through the query string |
|
|
201
|
-
| Redis | The path is the database number: `redis://host:6379/3` |
|
|
202
|
-
| Elasticsearch | `?api_key=...` authenticates with an API key; it is treated as a secret and never displayed |
|
|
114
|
+
Format (three slashes, then the full path to the file):
|
|
203
115
|
|
|
204
|
-
|
|
116
|
+
```text
|
|
117
|
+
sqlite:///[PATH_TO_FILE]
|
|
118
|
+
```
|
|
205
119
|
|
|
206
|
-
|
|
120
|
+
Example:
|
|
207
121
|
|
|
208
|
-
|
|
122
|
+
```text
|
|
123
|
+
sqlite:///Users/me/data/app.db
|
|
124
|
+
```
|
|
209
125
|
|
|
210
|
-
|
|
211
|
-
| --- | --- |
|
|
212
|
-
| `current_connection` | Which engine, server and database is active |
|
|
213
|
-
| `list_connections` | Available profiles and their engines, `*` marks the active one |
|
|
214
|
-
| `list_databases` | Databases on the connected server |
|
|
215
|
-
| `use_database` | Switch database on the current server |
|
|
216
|
-
| `use_connection` | Switch to a named profile, optional `database` override |
|
|
217
|
-
| `connect` | Open any server from a URL, optional `alias` |
|
|
126
|
+
The file is opened read-only.
|
|
218
127
|
|
|
219
|
-
|
|
128
|
+
> "What tables does this file have?" · "Show 10 rows from notes."
|
|
220
129
|
|
|
221
|
-
|
|
222
|
-
| --- | --- | --- | --- | --- |
|
|
223
|
-
| `list_tables` | tables and views | collections | keys, by SCAN | indices |
|
|
224
|
-
| `describe_table` | columns | fields inferred from 100 sampled documents | type, TTL, length | mapping |
|
|
225
|
-
| `get_table_indexes` | indexes | indexes | n/a | n/a |
|
|
226
|
-
| `get_foreign_keys` | foreign keys (not ClickHouse) | n/a | n/a | n/a |
|
|
227
|
-
| `get_table_sample` | up to 50 rows | up to 50 documents | the start of the value | up to 50 hits |
|
|
130
|
+
### SQL Server (and Azure SQL)
|
|
228
131
|
|
|
229
|
-
|
|
132
|
+
Format (usual port 1433). Add `?trustServerCertificate=true` for a local server with a self-signed certificate:
|
|
230
133
|
|
|
231
|
-
|
|
134
|
+
```text
|
|
135
|
+
mssql://[USER]:[PASSWORD]@[HOST]:[PORT]/[DATABASE]
|
|
136
|
+
```
|
|
232
137
|
|
|
233
|
-
|
|
234
|
-
| --- | --- | --- |
|
|
235
|
-
| `run_query` | SQL engines | One read-only statement in the engine's own dialect |
|
|
236
|
-
| `find_documents` | MongoDB | Filter, projection, sort, limit and skip, as Extended JSON |
|
|
237
|
-
| `aggregate` | MongoDB | A pipeline, without `$out` or `$merge` |
|
|
238
|
-
| `count_documents` | MongoDB | A filter |
|
|
239
|
-
| `distinct_values` | MongoDB | A field and an optional filter |
|
|
240
|
-
| `search` | Elasticsearch, OpenSearch | A Query DSL body; `size: 0` with `track_total_hits` counts |
|
|
241
|
-
| `redis_command` | Redis | One read-only command and its arguments |
|
|
138
|
+
Example:
|
|
242
139
|
|
|
243
|
-
|
|
140
|
+
```text
|
|
141
|
+
mssql://readonly:secret@localhost:1433/Sales?trustServerCertificate=true
|
|
142
|
+
```
|
|
244
143
|
|
|
245
|
-
|
|
144
|
+
> "List the tables in Sales." · "Show the top 5 customers by order total." (SQL Server uses `TOP 5`, not `LIMIT`; the assistant knows.)
|
|
246
145
|
|
|
247
|
-
|
|
146
|
+
### ClickHouse
|
|
248
147
|
|
|
249
|
-
|
|
148
|
+
Format (usual port 8123, or 8443 with `clickhouse+https`):
|
|
250
149
|
|
|
251
|
-
|
|
252
|
-
|
|
253
|
-
|
|
254
|
-
|
|
255
|
-
| `DB_PROFILES` | none | JSON object of named profiles |
|
|
256
|
-
| `DB_DEFAULT_PROFILE` | none | Which profile starts active |
|
|
257
|
-
| `DB_QUERY_TIMEOUT_MS` | `30000` | Statement timeout, enforced by each server where it can be |
|
|
258
|
-
| `DB_CONNECT_TIMEOUT_MS` | `10000` | Connection timeout |
|
|
259
|
-
| `DB_LOG` | off | `true` logs every tool call to stderr. See [Call logging](#call-logging) |
|
|
260
|
-
| `DB_LOG_FILE` | none | Log every tool call to this file instead |
|
|
261
|
-
| `DB_LOG_DIR` | none | Save every tool call as its own JSON file in this folder, permanently |
|
|
262
|
-
| `DB_LOG_FORMAT` | `pretty` | `pretty` or `json` |
|
|
263
|
-
| `DB_LOG_PORT` | none | Serve a live log viewer in the browser on this port |
|
|
264
|
-
| `DB_LOG_HISTORY` | `500` | Entries the viewer keeps in memory when there is no `DB_LOG_DIR` |
|
|
265
|
-
| `MYSQL_*` | | The legacy MySQL-only variables, read unchanged. See above |
|
|
150
|
+
```text
|
|
151
|
+
clickhouse://[USER]:[PASSWORD]@[HOST]:[PORT]/[DATABASE]
|
|
152
|
+
clickhouse+https://[USER]:[PASSWORD]@[HOST]:[PORT]/[DATABASE]
|
|
153
|
+
```
|
|
266
154
|
|
|
267
|
-
|
|
155
|
+
Example:
|
|
268
156
|
|
|
269
|
-
|
|
157
|
+
```text
|
|
158
|
+
clickhouse://reader:secret@localhost:8123/analytics
|
|
159
|
+
```
|
|
270
160
|
|
|
271
|
-
|
|
161
|
+
> "How many events per hour did we have yesterday?" · "What is the sorting key of the events table?"
|
|
272
162
|
|
|
273
|
-
|
|
163
|
+
### MongoDB
|
|
274
164
|
|
|
275
|
-
|
|
165
|
+
Format (usual port 27017). Use `mongodb+srv` for MongoDB Atlas, with no port:
|
|
276
166
|
|
|
277
|
-
|
|
278
|
-
|
|
279
|
-
|
|
280
|
-
|
|
281
|
-
| `DB_LOG_DIR=/path/folder` | Save every entry as its own JSON file in that folder, permanently. Implies logging on its own, without also writing text |
|
|
282
|
-
| `DB_LOG_FORMAT=json` | One JSON object per line, for `jq` or a log shipper. The default is `pretty` |
|
|
167
|
+
```text
|
|
168
|
+
mongodb://[USER]:[PASSWORD]@[HOST]:[PORT]/[DATABASE]?authSource=admin
|
|
169
|
+
mongodb+srv://[USER]:[PASSWORD]@[CLUSTER_HOST]/[DATABASE]
|
|
170
|
+
```
|
|
283
171
|
|
|
284
|
-
|
|
172
|
+
Example:
|
|
285
173
|
|
|
286
174
|
```text
|
|
287
|
-
|
|
288
|
-
│ connection dev (MySQL) mysql://reader@127.0.0.1:3306/app
|
|
289
|
-
│ input
|
|
290
|
-
│ {
|
|
291
|
-
│ "query": "SELECT COUNT(*) AS n FROM members"
|
|
292
|
-
│ }
|
|
293
|
-
│ statements (1)
|
|
294
|
-
│ 1. MySQL · 12 ms · 1 row
|
|
295
|
-
│ SELECT COUNT(*) AS n FROM members
|
|
296
|
-
│ output
|
|
297
|
-
│ [
|
|
298
|
-
│ {
|
|
299
|
-
│ "n": 17440
|
|
300
|
-
│ }
|
|
301
|
-
│ ]
|
|
302
|
-
└─
|
|
175
|
+
mongodb://reader:secret@localhost:27017/myapp?authSource=admin
|
|
303
176
|
```
|
|
304
177
|
|
|
305
|
-
|
|
306
|
-
- **Credentials never are.** A `password` argument, the password inside a connection URL, and secret-looking URL options such as `api_key` are always written as `***`, with no way to turn that off.
|
|
307
|
-
- **Statements** include the ones the server sends on its own behalf: PostgreSQL's `BEGIN READ ONLY` and `ROLLBACK`, Redis's `COMMAND INFO` checks, the catalog queries behind `describe_table`. Each shows its duration and outcome (a row count, or the error); the data itself is in the call's output. A statement sent outside any call, such as MySQL's per-connection setup, gets an entry of its own.
|
|
308
|
-
- An entry is written when its call finishes, and numbered when it starts, so calls handled concurrently can appear out of numeric order.
|
|
309
|
-
- With `DB_LOG_DIR`, each entry is its own file in a folder per UTC day, e.g. `2026-09-25/103014-221Z_p72440_c000012_run_query_ok.json`, holding the full record as pretty JSON: time, pid, sequence, tool and outcome are in the name, so `ls` and `grep` work without opening anything. Files and folders are readable by you only. Nothing is ever deleted or rotated; archive or remove old day folders yourself. Every copy of the server can share one folder, since names never collide.
|
|
310
|
-
- Logging can never break a call. If the log cannot be written (say, the disk is full), the call still succeeds, one warning is printed, and logging stops.
|
|
178
|
+
> "What collections are in myapp?" · "What fields do documents in users have?" · "Find the 5 most recent orders over 100." · "Count users by country."
|
|
311
179
|
|
|
312
|
-
|
|
180
|
+
### Redis (and Valkey, KeyDB)
|
|
313
181
|
|
|
314
|
-
|
|
182
|
+
Format (usual port 6379). `[DB_NUMBER]` is the database number, 0 if left out; `rediss` means TLS:
|
|
315
183
|
|
|
316
|
-
|
|
184
|
+
```text
|
|
185
|
+
redis://[USER]:[PASSWORD]@[HOST]:[PORT]/[DB_NUMBER]
|
|
186
|
+
rediss://[USER]:[PASSWORD]@[HOST]:[PORT]/[DB_NUMBER]
|
|
187
|
+
```
|
|
317
188
|
|
|
318
|
-
|
|
319
|
-
|
|
320
|
-
|
|
189
|
+
Example:
|
|
190
|
+
|
|
191
|
+
```text
|
|
192
|
+
redis://localhost:6379/0
|
|
321
193
|
```
|
|
322
194
|
|
|
323
|
-
|
|
324
|
-
| --- | --- | --- |
|
|
325
|
-
| `DB_LOG_PORT` | none | Serve the live viewer on this port. Needs `DB_LOG_DIR`, `DB_LOG` or `DB_LOG_FILE` as well; alone it only prints a warning |
|
|
326
|
-
| `DB_LOG_HISTORY` | `500` | Without `DB_LOG_DIR`, how many recent entries the viewer keeps in memory. `0` keeps none |
|
|
195
|
+
> "Which keys start with session:?" · "What's inside user:42?" · "How long until cache:home expires?"
|
|
327
196
|
|
|
328
|
-
|
|
197
|
+
### Elasticsearch and OpenSearch
|
|
329
198
|
|
|
330
|
-
|
|
199
|
+
Format (usual port 9200, no database). Add `+https` for TLS, or `?api_key=[API_KEY]` instead of a user and password:
|
|
331
200
|
|
|
332
|
-
|
|
201
|
+
```text
|
|
202
|
+
elasticsearch://[USER]:[PASSWORD]@[HOST]:[PORT]
|
|
203
|
+
opensearch://[USER]:[PASSWORD]@[HOST]:[PORT]
|
|
204
|
+
```
|
|
333
205
|
|
|
334
|
-
|
|
206
|
+
Example:
|
|
335
207
|
|
|
336
|
-
|
|
208
|
+
```text
|
|
209
|
+
elasticsearch+https://elastic:secret@search.example.com:9200
|
|
210
|
+
```
|
|
337
211
|
|
|
338
|
-
|
|
212
|
+
> "What indices do we have?" · "Find error logs from the last hour." · "How many documents are in logs-2026.09?"
|
|
339
213
|
|
|
340
|
-
|
|
214
|
+
Detailed notes for every database, including how to create a read-only account, are in the [Databases guide](https://github.com/shibbirweb/mcp-db-read-only/wiki/Databases).
|
|
341
215
|
|
|
342
216
|
---
|
|
343
217
|
|
|
344
|
-
##
|
|
218
|
+
## Using several databases
|
|
345
219
|
|
|
346
|
-
|
|
220
|
+
Give each one a name with `DB_PROFILES`, and switch by asking ("switch to legacy", "use the cache"):
|
|
347
221
|
|
|
348
|
-
|
|
349
|
-
|
|
350
|
-
|
|
351
|
-
|
|
352
|
-
|
|
353
|
-
|
|
354
|
-
| ClickHouse | SQL validator, refusing table functions that reach outside the server | ClickHouse's own `readonly` setting on every query |
|
|
355
|
-
| MongoDB | Operator denylist: `$out`, `$merge`, `$function`, `$where` anywhere | Stage allowlist in the driver, which only ever calls read operations |
|
|
356
|
-
| Redis | Command allowlist | The server's own `COMMAND INFO` flags: a command is sent only if Redis itself calls it read-only |
|
|
357
|
-
| Elasticsearch | Search body allowlist; index names cannot address an API | The driver can only reach fixed read endpoints |
|
|
222
|
+
```json
|
|
223
|
+
"env": {
|
|
224
|
+
"DB_PROFILES": "{\"app\": \"postgres://readonly@localhost/app\", \"legacy\": \"mysql://readonly@localhost/shop\", \"cache\": \"redis://localhost:6379/0\"}",
|
|
225
|
+
"DB_DEFAULT_PROFILE": "app"
|
|
226
|
+
}
|
|
227
|
+
```
|
|
358
228
|
|
|
359
|
-
|
|
229
|
+
You can also connect to a database you didn't list, mid-conversation: *"connect to postgres://readonly@10.0.0.5/reports"*.
|
|
360
230
|
|
|
361
|
-
|
|
231
|
+
**Password with special characters** (`@`, `/`, `#`)? Give it separately instead of inside the URL: `DB_PASSWORD` next to `DB_URL`, or `{"url": "...", "password": "..."}` inside `DB_PROFILES`.
|
|
362
232
|
|
|
363
|
-
|
|
233
|
+
---
|
|
364
234
|
|
|
365
|
-
|
|
235
|
+
## Running with Docker
|
|
366
236
|
|
|
367
|
-
|
|
237
|
+
Nothing to install but Docker:
|
|
368
238
|
|
|
369
|
-
```
|
|
370
|
-
|
|
371
|
-
|
|
372
|
-
|
|
373
|
-
|
|
239
|
+
```json
|
|
240
|
+
{
|
|
241
|
+
"mcpServers": {
|
|
242
|
+
"databases": {
|
|
243
|
+
"command": "docker",
|
|
244
|
+
"args": [
|
|
245
|
+
"run", "-i", "--rm",
|
|
246
|
+
"--add-host", "host.docker.internal:host-gateway",
|
|
247
|
+
"-e", "DB_URL=postgres://readonly:secret@host.docker.internal:5432/myapp",
|
|
248
|
+
"shibbirweb/mcp-db-read-only"
|
|
249
|
+
]
|
|
250
|
+
}
|
|
251
|
+
}
|
|
252
|
+
}
|
|
374
253
|
```
|
|
375
254
|
|
|
376
|
-
|
|
377
|
-
|
|
378
|
-
|
|
255
|
+
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`.
|
|
256
|
+
|
|
257
|
+
---
|
|
258
|
+
|
|
259
|
+
## Watching what the assistant does
|
|
260
|
+
|
|
261
|
+
Turn on logging to keep a record of every query the assistant runs, and see them live in your browser.
|
|
262
|
+
|
|
263
|
+
```mermaid
|
|
264
|
+
flowchart LR
|
|
265
|
+
S["mcp-db-read-only<br/>(in your AI client)"] -->|"one file per call"| F[("Log folder<br/>DB_LOG_DIR")]
|
|
266
|
+
F --> V["viewer command<br/>(in a terminal)"]
|
|
267
|
+
V -->|"live"| B["Your browser"]
|
|
379
268
|
```
|
|
380
269
|
|
|
381
|
-
|
|
382
|
-
|
|
383
|
-
|
|
270
|
+
**1. Save logs to a folder** by adding this to the server's `env`:
|
|
271
|
+
|
|
272
|
+
```json
|
|
273
|
+
"DB_LOG_DIR": "/Users/me/Library/Logs/mcp-db-read-only"
|
|
384
274
|
```
|
|
385
275
|
|
|
386
|
-
|
|
276
|
+
Each query is saved as its own file, one folder per day. Nothing is ever deleted automatically.
|
|
387
277
|
|
|
388
|
-
|
|
389
|
-
- A column named exactly like a write keyword must be quoted where the validator scans for them: inside `WITH` queries, and in every SQL Server statement.
|
|
390
|
-
- SQLite queries run in a separate process, so one that exceeds the timeout can be killed outright.
|
|
278
|
+
**2. Open the viewer** in a terminal, whenever you want to watch:
|
|
391
279
|
|
|
392
|
-
|
|
280
|
+
```bash
|
|
281
|
+
npx -y @shibbirweb/mcp-db-read-only viewer --dir /Users/me/Library/Logs/mcp-db-read-only --port 4800
|
|
282
|
+
```
|
|
393
283
|
|
|
394
|
-
|
|
284
|
+
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.
|
|
395
285
|
|
|
396
|
-
|
|
286
|
+
> The viewer has no password. Anyone who can reach that port on your network can read the log while it runs.
|
|
397
287
|
|
|
398
|
-
|
|
288
|
+
Passwords are never written to the logs. More in the [Logging guide](https://github.com/shibbirweb/mcp-db-read-only/wiki/Logging-and-Viewer).
|
|
399
289
|
|
|
400
290
|
---
|
|
401
291
|
|
|
402
|
-
##
|
|
292
|
+
## Is it really read-only?
|
|
403
293
|
|
|
404
|
-
|
|
294
|
+
Yes, in two independent ways, so a mistake in one is caught by the other:
|
|
405
295
|
|
|
406
|
-
```
|
|
407
|
-
|
|
408
|
-
|
|
409
|
-
|
|
410
|
-
|
|
296
|
+
```mermaid
|
|
297
|
+
flowchart LR
|
|
298
|
+
Q["The assistant<br/>writes a query"] --> C{"1. Checked by<br/>this server:<br/>only a read?"}
|
|
299
|
+
C -->|"no"| R1["Refused,<br/>with the reason"]
|
|
300
|
+
C -->|"yes"| D["2. Sent to the database<br/>in read-only mode"]
|
|
301
|
+
D -->|"a read"| A["The answer"]
|
|
302
|
+
D -->|"a write that<br/>slipped through"| R2["Refused by<br/>the database"]
|
|
411
303
|
```
|
|
412
304
|
|
|
413
|
-
|
|
305
|
+
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.
|
|
306
|
+
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.
|
|
414
307
|
|
|
415
|
-
|
|
308
|
+
**The best protection is still a read-only database account.** Then nothing can write through it, whatever happens. The [Databases guide](https://github.com/shibbirweb/mcp-db-read-only/wiki/Databases) shows how to create one for each database.
|
|
416
309
|
|
|
417
|
-
|
|
418
|
-
npm ci
|
|
419
|
-
npm run build
|
|
420
|
-
npm run test:unit # no database needed
|
|
421
|
-
npm test # integration suites skip any engine they cannot reach
|
|
422
|
-
```
|
|
310
|
+
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](PRIVACY.md).
|
|
423
311
|
|
|
424
|
-
|
|
312
|
+
---
|
|
425
313
|
|
|
426
|
-
|
|
314
|
+
## Settings
|
|
427
315
|
|
|
428
|
-
|
|
429
|
-
src/
|
|
430
|
-
index.ts Entry point
|
|
431
|
-
ApplicationFactory.ts Composition root: the only file that wires things, and the only one naming a driver
|
|
432
|
-
types/ Interfaces and type aliases, one file per concern
|
|
433
|
-
errors/ Named error classes
|
|
434
|
-
domain/ Engine catalog, ConnectionTarget, ConnectionProfile
|
|
435
|
-
config/ Reading configuration from the environment
|
|
436
|
-
connections/ URL parser, target factory, profile registry, connection manager
|
|
437
|
-
drivers/ DatabaseDriver strategy, registry, LRU cache, and sql/ document/ keyvalue/ search/
|
|
438
|
-
validation/ sql/ (dialects, skeletonizer, rules), document/, keyvalue/, search/, names/
|
|
439
|
-
formatting/ Response, row and JSON rendering
|
|
440
|
-
tools/ BaseTool, DatabaseScopedTool, connection/ browse/ sql/ document/ search/ keyvalue/
|
|
441
|
-
server/ McpDbServer
|
|
442
|
-
```
|
|
316
|
+
All optional. Set them in the server's `env`.
|
|
443
317
|
|
|
444
|
-
|
|
318
|
+
| Setting | What it does |
|
|
319
|
+
| --- | --- |
|
|
320
|
+
| `DB_URL` | The database to connect to at startup |
|
|
321
|
+
| `DB_PASSWORD` | The password for `DB_URL`, if you'd rather keep it out of the URL |
|
|
322
|
+
| `DB_PROFILES` | Several named databases, as JSON, to switch between |
|
|
323
|
+
| `DB_DEFAULT_PROFILE` | Which of those to start with |
|
|
324
|
+
| `DB_QUERY_TIMEOUT_MS` | Stop a query after this long (default 30000, that is 30 seconds) |
|
|
325
|
+
| `DB_CONNECT_TIMEOUT_MS` | Give up connecting after this long (default 10000) |
|
|
326
|
+
| `DB_LOG_DIR` | Save every call as a file in this folder |
|
|
327
|
+
| `DB_LOG=true` | Write every call to the client's log instead |
|
|
328
|
+
| `DB_LOG_FILE` | Write every call to one file instead |
|
|
329
|
+
| `DB_LOG_FORMAT` | `pretty` (default) or `json`, for `DB_LOG` and `DB_LOG_FILE` |
|
|
330
|
+
| `DB_LOG_PORT` | Run the viewer inside the server itself (the separate `viewer` command is usually better) |
|
|
331
|
+
|
|
332
|
+
Coming from `mcp-mysql-read-only`? Its `MYSQL_HOST`, `MYSQL_USER`, `MYSQL_PASSWORD`, `MYSQL_DATABASE` and `MYSQL_PROFILES` settings still work as they are.
|
|
333
|
+
|
|
334
|
+
Full details: [Configuration guide](https://github.com/shibbirweb/mcp-db-read-only/wiki/Configuration).
|
|
445
335
|
|
|
446
336
|
---
|
|
447
337
|
|
|
448
|
-
##
|
|
338
|
+
## Troubleshooting
|
|
339
|
+
|
|
340
|
+
**"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.
|
|
341
|
+
|
|
342
|
+
**The server won't start with npx.** Check `node --version` is 22.13 or newer.
|
|
449
343
|
|
|
450
|
-
|
|
344
|
+
**SQL Server says the certificate isn't trusted.** Add `?trustServerCertificate=true` to the URL for a local or development server.
|
|
451
345
|
|
|
452
|
-
|
|
346
|
+
**"No database selected".** Your URL has no database name. Add one (`.../myapp`), or ask the assistant to list the databases and pick one.
|
|
453
347
|
|
|
454
|
-
|
|
348
|
+
**My password has `@` or `#` in it.** Use `DB_PASSWORD`, or the `{"url": ..., "password": ...}` form in `DB_PROFILES`.
|
|
455
349
|
|
|
456
|
-
|
|
350
|
+
**The viewer says the port is in use.** Something else is using it. Close that, or pick another port with `--port 4801`.
|
|
351
|
+
|
|
352
|
+
More answers in the [Troubleshooting guide](https://github.com/shibbirweb/mcp-db-read-only/wiki/Troubleshooting).
|
|
353
|
+
|
|
354
|
+
---
|
|
457
355
|
|
|
458
|
-
##
|
|
356
|
+
## Learn more
|
|
459
357
|
|
|
460
|
-
|
|
358
|
+
- [Wiki](https://github.com/shibbirweb/mcp-db-read-only/wiki): user guides for every feature, plus developer documentation
|
|
359
|
+
- [CHANGELOG.md](CHANGELOG.md): what changed in each version
|
|
360
|
+
- [PRIVACY.md](PRIVACY.md): what the server sends where (nothing, except to your databases)
|
|
361
|
+
- 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](https://github.com/shibbirweb/mcp-db-read-only/wiki/Testing). If you change this README, change [README.dockerhub.md](README.dockerhub.md) to match.
|
|
461
362
|
|
|
462
363
|
## License
|
|
463
364
|
|