dbmastermind-mcp 0.0.0-stage → 1.5.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/LICENSE +21 -0
- package/README.md +128 -2
- package/dist/cli.js +81086 -0
- package/dist/dbm.js +82491 -0
- package/package.json +79 -4
- package/server.json +35 -0
package/LICENSE
ADDED
|
@@ -0,0 +1,21 @@
|
|
|
1
|
+
MIT License
|
|
2
|
+
|
|
3
|
+
Copyright (c) 2026 Václav Mudra and DB Mastermind contributors
|
|
4
|
+
|
|
5
|
+
Permission is hereby granted, free of charge, to any person obtaining a copy
|
|
6
|
+
of this software and associated documentation files (the "Software"), to deal
|
|
7
|
+
in the Software without restriction, including without limitation the rights
|
|
8
|
+
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
|
|
9
|
+
copies of the Software, and to permit persons to whom the Software is
|
|
10
|
+
furnished to do so, subject to the following conditions:
|
|
11
|
+
|
|
12
|
+
The above copyright notice and this permission notice shall be included in all
|
|
13
|
+
copies or substantial portions of the Software.
|
|
14
|
+
|
|
15
|
+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
|
|
16
|
+
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
|
|
17
|
+
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
|
|
18
|
+
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
|
|
19
|
+
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
|
|
20
|
+
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
|
|
21
|
+
SOFTWARE.
|
package/README.md
CHANGED
|
@@ -1,3 +1,129 @@
|
|
|
1
|
-
#
|
|
1
|
+
# dbmastermind-mcp
|
|
2
2
|
|
|
3
|
-
|
|
3
|
+
An MCP server that lets AI agents (Claude Code, Codex, Cursor, Claude Desktop, VS Code and others) explore and
|
|
4
|
+
query your databases, read-only unless you allow writes. The package also installs `dbm`, a command line for
|
|
5
|
+
scripts and CI.
|
|
6
|
+
|
|
7
|
+
**PostgreSQL · SQL Server · Oracle · MySQL · MariaDB · SQLite · DuckDB · ClickHouse · BigQuery · Trino ·
|
|
8
|
+
CockroachDB.** Hosted services that run one of these engines work the same way (Supabase, Neon, Amazon RDS,
|
|
9
|
+
Azure SQL, Google Cloud SQL and others).
|
|
10
|
+
|
|
11
|
+
Needs Node.js 22.16 or newer. Free and open source (MIT).
|
|
12
|
+
|
|
13
|
+
## Quick start
|
|
14
|
+
|
|
15
|
+
Claude Code:
|
|
16
|
+
|
|
17
|
+
```bash
|
|
18
|
+
claude mcp add shop -- npx -y dbmastermind-mcp --url 'postgres://me:${PGPASSWORD}@localhost:5432/shop'
|
|
19
|
+
```
|
|
20
|
+
|
|
21
|
+
Codex (`~/.codex/config.toml`):
|
|
22
|
+
|
|
23
|
+
```toml
|
|
24
|
+
[mcp_servers.shop]
|
|
25
|
+
command = "npx"
|
|
26
|
+
args = ["-y", "dbmastermind-mcp", "--url", "jdbc:sqlserver://sql01:1433;databaseName=Sales;user=report;password=${SQL_PASSWORD};trustServerCertificate=true"]
|
|
27
|
+
```
|
|
28
|
+
|
|
29
|
+
Claude Desktop, Cursor, Windsurf, Gemini CLI and other clients with a JSON config:
|
|
30
|
+
|
|
31
|
+
```json
|
|
32
|
+
{
|
|
33
|
+
"mcpServers": {
|
|
34
|
+
"shop": {
|
|
35
|
+
"command": "npx",
|
|
36
|
+
"args": ["-y", "dbmastermind-mcp", "--url", "sqlite:///Users/me/data/shop.db"]
|
|
37
|
+
}
|
|
38
|
+
}
|
|
39
|
+
}
|
|
40
|
+
```
|
|
41
|
+
|
|
42
|
+
VS Code uses the key `servers` instead of `mcpServers`.
|
|
43
|
+
|
|
44
|
+
`${NAME}` in a URL or a `--config` file is replaced with the environment variable `NAME` when the server starts, so
|
|
45
|
+
passwords don't have to be written into the agent's configuration. In a shell, keep such a URL in single quotes (or
|
|
46
|
+
the shell replaces it first), and make sure the agent passes the variable to the servers it starts; most clients take
|
|
47
|
+
an `env` entry next to `command` and `args`.
|
|
48
|
+
|
|
49
|
+
## Connection URLs
|
|
50
|
+
|
|
51
|
+
| Database | `--url` |
|
|
52
|
+
|---|---|
|
|
53
|
+
| PostgreSQL, CockroachDB | `postgres://user:password@host:5432/db?sslmode=require` |
|
|
54
|
+
| SQL Server | `sqlserver://user:password@host:1433/db`, JDBC (`jdbc:sqlserver://host:1433;databaseName=db;user=…;password=…`) or ADO.NET (`Server=host,1433;Database=db;User Id=…;Password=…`) |
|
|
55
|
+
| Oracle | `oracle://user:password@host:1521/service` or `jdbc:oracle:thin:user/password@host:1521/service` |
|
|
56
|
+
| MySQL, MariaDB | `mysql://user:password@host:3306/db`, `mariadb://…` |
|
|
57
|
+
| SQLite | `sqlite:///path/to/file.db` |
|
|
58
|
+
| DuckDB | `duckdb:///path/to/file.duckdb`, or `duckdb://` for an in-memory database |
|
|
59
|
+
| ClickHouse | `clickhouse://user:password@host:8123/db` |
|
|
60
|
+
| Trino | `trino://user@host:8080/catalog/schema` |
|
|
61
|
+
| BigQuery | with `--config`: `{ "name": "bq", "driver": "bigquery", "database": "<project id>", "filePath": "<service account key.json>" }` (without `filePath`, Google's application default credentials) |
|
|
62
|
+
|
|
63
|
+
JDBC URLs (`jdbc:postgresql://…?user=…&password=…`) work as well.
|
|
64
|
+
|
|
65
|
+
## What agents get
|
|
66
|
+
|
|
67
|
+
- **Schema**: `list_connections`, `list_tables`, `describe_table` (columns, keys, indexes, comments, incoming
|
|
68
|
+
references), `search_schema`, `get_relationships`, `find_join_path` (the shortest join chain, with ready SQL),
|
|
69
|
+
`get_definition` (the SQL of a view, function or procedure; a table's CREATE)
|
|
70
|
+
- **Data**: `sample_rows`, `run_query` (results as compact CSV), `explain_query` (the plan as a tree)
|
|
71
|
+
- **Knowledge base**: point `--knowledge` at a folder of Markdown notes about the database. Agents search and
|
|
72
|
+
read them (`search_knowledge`, `read_knowledge`), and relationships declared there
|
|
73
|
+
(`relations: ["orders.customer_code -> customers.code"]`) count as foreign keys. With
|
|
74
|
+
`--allow-knowledge-writes` they can also add notes (`write_knowledge`).
|
|
75
|
+
- **Prompts**: `explore_database`, `document_database`
|
|
76
|
+
|
|
77
|
+
**Read-only by default.** Without `--allow-writes`, statements run in a read-only transaction that is always rolled
|
|
78
|
+
back, so a function that writes or a statement that only looks like a SELECT can't change anything. With
|
|
79
|
+
`--read-only` the database session itself is read-only where the engine supports it. `--schema-only` never
|
|
80
|
+
returns table contents.
|
|
81
|
+
|
|
82
|
+
## Options
|
|
83
|
+
|
|
84
|
+
| Flag | |
|
|
85
|
+
|---|---|
|
|
86
|
+
| `--url <url>` | A connection (see above). Repeat it for several databases. |
|
|
87
|
+
| `--name <name>` | Name for the preceding `--url` (default: host/database) |
|
|
88
|
+
| `--knowledge <dir>` | Knowledge base folder for the preceding `--url` |
|
|
89
|
+
| `--config <file>` | JSON array of connections: `name`, `url` or `driver`/`host`/`port`/`database`/`user`/`password`, `knowledgeBase`, `readOnly`, `files` |
|
|
90
|
+
| `--allow-files <path>` | DuckDB: a file or folder agents may read, for the preceding `--url` (repeatable; `"files": [...]` in `--config`). Without it only the database file is readable. |
|
|
91
|
+
| `--allow-writes` | Allow INSERT, UPDATE, DELETE and DDL |
|
|
92
|
+
| `--allow-knowledge-writes` | Let agents create knowledge base files |
|
|
93
|
+
| `--schema-only` | Never return table contents |
|
|
94
|
+
| `--read-only` | Mark every connection read-only (enforced by the database where supported) |
|
|
95
|
+
|
|
96
|
+
## `dbm`: the command line
|
|
97
|
+
|
|
98
|
+
The same connections (`--url`, `--config`, `${ENV}` placeholders) for scripts and CI:
|
|
99
|
+
|
|
100
|
+
```bash
|
|
101
|
+
npx -p dbmastermind-mcp dbm query --url "$DATABASE_URL" "SELECT * FROM orders WHERE created_at > now() - interval '1 day'" --format csv --out orders.csv
|
|
102
|
+
npx -p dbmastermind-mcp dbm dictionary --url "$DATABASE_URL" --format html --out docs/database.html
|
|
103
|
+
npx -p dbmastermind-mcp dbm check model.dbml # model checks; exit 1 when a table has problems
|
|
104
|
+
npx -p dbmastermind-mcp dbm diff model.dbml --url "$DATABASE_URL" # exit 2 and the migration when the database drifted
|
|
105
|
+
```
|
|
106
|
+
|
|
107
|
+
`query` streams one SELECT of any size (csv, tsv, json, jsonl, markdown) and is read-only unless `--allow-writes`.
|
|
108
|
+
DuckDB reads other files only when they are allowed, and compares the path as written, so use absolute paths:
|
|
109
|
+
|
|
110
|
+
```bash
|
|
111
|
+
npx -p dbmastermind-mcp dbm query --url duckdb:///data/shop.duckdb --allow-files /data/exports "SELECT count(*) FROM read_csv('/data/exports/*.csv')"
|
|
112
|
+
```
|
|
113
|
+
|
|
114
|
+
`diff` never changes the database and keeps tables only the database has unless `--drop-extra`.
|
|
115
|
+
`npx -p dbmastermind-mcp dbm --help` lists everything.
|
|
116
|
+
|
|
117
|
+
## The desktop app
|
|
118
|
+
|
|
119
|
+
This package is part of [DB Mastermind](https://dbmastermind.app), a free, open-source database client and data
|
|
120
|
+
modeler for Windows, macOS and Linux. The app can be the MCP server too, with your saved connections and the
|
|
121
|
+
passwords in your system keychain (Settings → MCP server), and there agents can also propose a new connection,
|
|
122
|
+
which you review and save in the app.
|
|
123
|
+
|
|
124
|
+
- Website: [dbmastermind.app](https://dbmastermind.app) · [Privacy](https://dbmastermind.app/privacy.html)
|
|
125
|
+
- Source and issues: [github.com/eLh0m3r0/db-mastermind](https://github.com/eLh0m3r0/db-mastermind)
|
|
126
|
+
|
|
127
|
+
## License
|
|
128
|
+
|
|
129
|
+
MIT
|