@futuretea/postgres-mcp-server 0.0.1 → 0.2.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/README.md +190 -4
- package/package.json +6 -6
package/README.md
CHANGED
|
@@ -1,13 +1,20 @@
|
|
|
1
1
|
# PostgreSQL Read-only MCP Server
|
|
2
2
|
|
|
3
|
+
[中文](README.zh.md)
|
|
4
|
+
|
|
3
5
|
An MCP (Model Context Protocol) server for discovering one PostgreSQL 17+ instance and running a deliberately narrow SELECT subset. It exposes MCP over stdio or HTTP and includes a CLI.
|
|
4
6
|
|
|
5
7
|
## Quick start
|
|
6
8
|
|
|
7
|
-
Set
|
|
9
|
+
Set discrete connection fields for a minimally privileged PostgreSQL role, then build and inspect the catalog. A valid UTF-8 password is a normal environment value here and does not need URL encoding. A password that is not valid UTF-8 is rejected before connect, and the error does not include the password.
|
|
8
10
|
|
|
9
11
|
```sh
|
|
10
|
-
export
|
|
12
|
+
export MCP_POSTGRES_HOST=127.0.0.1
|
|
13
|
+
export MCP_POSTGRES_PORT=5432
|
|
14
|
+
export MCP_POSTGRES_DATABASE=app
|
|
15
|
+
export MCP_POSTGRES_USERNAME=reader
|
|
16
|
+
export MCP_POSTGRES_PASSWORD='<runtime-secret>'
|
|
17
|
+
export MCP_POSTGRES_SSLMODE=disable
|
|
11
18
|
make build
|
|
12
19
|
./bin/postgres-mcp-server tools list
|
|
13
20
|
./bin/postgres-mcp-server mcp
|
|
@@ -15,6 +22,97 @@ make build
|
|
|
15
22
|
|
|
16
23
|
`tools list` and `tools describe` do not read database connection settings. Starting MCP/HTTP or calling a tool validates the connection and verifies the server and role before it reports ready.
|
|
17
24
|
|
|
25
|
+
## Use a release
|
|
26
|
+
|
|
27
|
+
Release `v0.0.1` is available as an npm package and a multi-architecture Docker image. Both release entry points start MCP over stdio by default.
|
|
28
|
+
|
|
29
|
+
### npm
|
|
30
|
+
|
|
31
|
+
Run the published package with `npx`:
|
|
32
|
+
|
|
33
|
+
```sh
|
|
34
|
+
export DATABASE_URL='postgres://reader@127.0.0.1:5432/app?sslmode=disable'
|
|
35
|
+
npx -y @futuretea/postgres-mcp-server@0.0.1
|
|
36
|
+
```
|
|
37
|
+
|
|
38
|
+
For an MCP client configuration, use:
|
|
39
|
+
|
|
40
|
+
```json
|
|
41
|
+
{
|
|
42
|
+
"mcpServers": {
|
|
43
|
+
"postgres-readonly": {
|
|
44
|
+
"command": "npx",
|
|
45
|
+
"args": ["-y", "@futuretea/postgres-mcp-server@0.0.1"],
|
|
46
|
+
"env": {
|
|
47
|
+
"DATABASE_URL": "postgres://reader@127.0.0.1:5432/app?sslmode=disable"
|
|
48
|
+
}
|
|
49
|
+
}
|
|
50
|
+
}
|
|
51
|
+
}
|
|
52
|
+
```
|
|
53
|
+
|
|
54
|
+
The npm command is an MCP entry point, not a wrapper for the server's other CLI subcommands. Pin the package version you intend to run.
|
|
55
|
+
|
|
56
|
+
### Docker
|
|
57
|
+
|
|
58
|
+
Run the published image directly:
|
|
59
|
+
|
|
60
|
+
```sh
|
|
61
|
+
export DATABASE_URL='postgres://reader@db.example.internal:5432/app?sslmode=require'
|
|
62
|
+
docker run --rm -i \
|
|
63
|
+
--env DATABASE_URL \
|
|
64
|
+
ghcr.io/futuretea/postgres-mcp-server:v0.0.1
|
|
65
|
+
```
|
|
66
|
+
|
|
67
|
+
For an MCP client that launches Docker, pass the connection settings through the Docker process:
|
|
68
|
+
|
|
69
|
+
```json
|
|
70
|
+
{
|
|
71
|
+
"mcpServers": {
|
|
72
|
+
"postgres-readonly": {
|
|
73
|
+
"command": "docker",
|
|
74
|
+
"args": [
|
|
75
|
+
"run",
|
|
76
|
+
"--rm",
|
|
77
|
+
"-i",
|
|
78
|
+
"--env",
|
|
79
|
+
"DATABASE_URL",
|
|
80
|
+
"ghcr.io/futuretea/postgres-mcp-server:v0.0.1"
|
|
81
|
+
],
|
|
82
|
+
"env": {
|
|
83
|
+
"DATABASE_URL": "postgres://reader@db.example.internal:5432/app?sslmode=require"
|
|
84
|
+
}
|
|
85
|
+
}
|
|
86
|
+
}
|
|
87
|
+
}
|
|
88
|
+
```
|
|
89
|
+
|
|
90
|
+
The database hostname must be reachable from the container. `localhost` inside the container is not the host machine; use a database hostname on the Docker network, or the platform-specific host gateway when appropriate.
|
|
91
|
+
|
|
92
|
+
The Docker examples use `sslmode=require` for a remote database. Set the PostgreSQL TLS mode and certificates required by your deployment.
|
|
93
|
+
|
|
94
|
+
### HTTP mode
|
|
95
|
+
|
|
96
|
+
Pass MCP flags after the release command to start HTTP instead of stdio. On the host, the default listener is loopback:
|
|
97
|
+
|
|
98
|
+
```sh
|
|
99
|
+
export DATABASE_URL='postgres://reader@127.0.0.1:5432/app?sslmode=disable'
|
|
100
|
+
npx -y @futuretea/postgres-mcp-server@0.0.1 --port 8080
|
|
101
|
+
```
|
|
102
|
+
|
|
103
|
+
For Docker, the server must listen on all container interfaces, while the published port can remain loopback-only on the host:
|
|
104
|
+
|
|
105
|
+
```sh
|
|
106
|
+
export DATABASE_URL='postgres://reader@db.example.internal:5432/app?sslmode=require'
|
|
107
|
+
docker run --rm \
|
|
108
|
+
--env DATABASE_URL \
|
|
109
|
+
--publish 127.0.0.1:8080:8080 \
|
|
110
|
+
ghcr.io/futuretea/postgres-mcp-server:v0.0.1 \
|
|
111
|
+
--port 8080 --listen 0.0.0.0
|
|
112
|
+
```
|
|
113
|
+
|
|
114
|
+
Use `http://127.0.0.1:8080/mcp` for Streamable HTTP MCP clients. The server also provides SSE at `/sse` with messages at `/message`, and `GET /healthz` for health checks. HTTP has no authentication or TLS; keep it on a trusted network or place it behind infrastructure that provides both.
|
|
115
|
+
|
|
18
116
|
## Tools
|
|
19
117
|
|
|
20
118
|
| Tool | Parameters | Purpose |
|
|
@@ -31,10 +129,91 @@ Every successful tool response is one JSON text envelope with `schema_version`,
|
|
|
31
129
|
|
|
32
130
|
## Database connection
|
|
33
131
|
|
|
34
|
-
|
|
132
|
+
Set discrete environment variables. Do not put the host, password, or a connection URL in YAML. A valid UTF-8 password does not need URL encoding.
|
|
133
|
+
|
|
134
|
+
| Variable | libpq alias | Required without `DATABASE_URL` or `PGSERVICE` | Default |
|
|
135
|
+
|---|---|---|---|
|
|
136
|
+
| `MCP_POSTGRES_HOST` | `PGHOST` | yes | none |
|
|
137
|
+
| `MCP_POSTGRES_PORT` | `PGPORT` | no | `5432` |
|
|
138
|
+
| `MCP_POSTGRES_DATABASE` | `PGDATABASE` | yes | none |
|
|
139
|
+
| `MCP_POSTGRES_USERNAME` | `PGUSER` | yes | none |
|
|
140
|
+
| `MCP_POSTGRES_PASSWORD` | `PGPASSWORD` | no | empty |
|
|
141
|
+
| `MCP_POSTGRES_SSLMODE` | `PGSSLMODE` | no | `prefer` |
|
|
142
|
+
|
|
143
|
+
`MCP_POSTGRES_*` matches this server's `MCP_` environment prefix and the ClickHouse server's `MCP_CLICKHOUSE_*` connection fields (`MCP_CLICKHOUSE_DATABASE`, `MCP_CLICKHOUSE_USERNAME`, `MCP_CLICKHOUSE_PASSWORD`). MySQL uses `MYSQL_MCP_*` because that repository prefixes every variable, including its HTTP port, with `MYSQL_MCP_`. `MCP_POSTGRES_PORT` is the database port. The HTTP port remains `MCP_PORT`.
|
|
144
|
+
|
|
145
|
+
Each `MCP_POSTGRES_*` variable is an alias of the `PG*` variable in the same row. If both names are set to different values, startup fails. The error names the two variables and does not print their values. `MCP_POSTGRES_*` is an explicit connection parameter, so it overrides a `PGSERVICE` entry for that field. When the `MCP_POSTGRES_*` alias is unset, a service file still overrides `PG*`, which is pgx's existing libpq behavior.
|
|
146
|
+
|
|
147
|
+
An unset `MCP_POSTGRES_PASSWORD` leaves `PGPASSWORD` and `.pgpass` in place. An empty `PGPASSWORD` is unset, matching libpq. Setting `MCP_POSTGRES_PASSWORD` to an empty string is an explicit empty password: it overrides `PGPASSWORD` and `.pgpass`. If that empty value and a non-empty `PGPASSWORD` are both set, startup fails and the error names the two variables without printing them.
|
|
148
|
+
|
|
149
|
+
The resolved password must be valid UTF-8. This applies to `MCP_POSTGRES_PASSWORD`, `PGPASSWORD`, a `DATABASE_URL` password, a service-file password, and a `.pgpass` password. Invalid UTF-8 fails configuration with `[postgres_invalid_config] password must be valid UTF-8` and the value is not printed. Keeping the original bytes in the connection config is not authentication: pgx's SCRAM preparation replaces those bytes with U+FFFD and would send a different password.
|
|
150
|
+
|
|
151
|
+
`PGSERVICE` can supply the required fields from a PostgreSQL service file. Without `DATABASE_URL` or `PGSERVICE`, host, database, and username are required. Libpq defaults for those three fields are not used, so a partial `PG*` setup that omits one of them fails. A missing required field produces an error that names the absent variables, for example `[postgres_invalid_config] missing MCP_POSTGRES_HOST or PGHOST, MCP_POSTGRES_DATABASE or PGDATABASE, MCP_POSTGRES_USERNAME or PGUSER`.
|
|
152
|
+
|
|
153
|
+
Configuration must resolve to one `host:port`. Distinct URL targets or comma-separated hosts are rejected before a connection is created.
|
|
154
|
+
|
|
155
|
+
### `DATABASE_URL` (optional)
|
|
156
|
+
|
|
157
|
+
`DATABASE_URL` remains an advanced alternative for a libpq URL you already have. When it is set, that URL is the connection string and every `MCP_POSTGRES_*` variable is ignored. Standard `PG*` variables still fill settings the URL omits, and a setting present in the URL overrides the same `PG*` variable. Leave `DATABASE_URL` unset to use the discrete fields above.
|
|
158
|
+
|
|
159
|
+
```sh
|
|
160
|
+
export DATABASE_URL='postgres://reader@127.0.0.1:5432/app?sslmode=disable'
|
|
161
|
+
```
|
|
162
|
+
|
|
163
|
+
A password in `DATABASE_URL` must be URL-encoded. Prefer `MCP_POSTGRES_PASSWORD` when the password contains reserved characters.
|
|
35
164
|
|
|
36
165
|
At startup the server requires PostgreSQL 17 or newer and rejects service roles that are superusers, bypass row-level security, have replication, or belong to server-file, server-program, or backend-signalling roles. Use a dedicated, least-privilege database role.
|
|
37
166
|
|
|
167
|
+
If you cannot provision such a role, set `allow_unsafe_database_role: true` (`MCP_ALLOW_UNSAFE_DATABASE_ROLE=true` for the environment) to skip only this role check. The server still wraps every statement in a read-only transaction, but the role-level guarantee is gone: a superuser role can read tables you did not intend to expose, read server files, and run server-side programs that a read-only transaction does not constrain, and a `BYPASSRLS` role sees through row-level security policies. Enable it only against a database you control.
|
|
168
|
+
|
|
169
|
+
### Create a read-only service role
|
|
170
|
+
|
|
171
|
+
Run the following in `psql` as a database administrator. Replace `app` and `public` with your database and schema. This creates a fresh login role with no inherited privileges; do not reuse an administrator or application-owner role.
|
|
172
|
+
|
|
173
|
+
```sql
|
|
174
|
+
CREATE ROLE mcp_reader
|
|
175
|
+
LOGIN
|
|
176
|
+
NOSUPERUSER NOCREATEDB NOCREATEROLE
|
|
177
|
+
NOINHERIT NOREPLICATION NOBYPASSRLS;
|
|
178
|
+
\password mcp_reader
|
|
179
|
+
|
|
180
|
+
GRANT CONNECT ON DATABASE app TO mcp_reader;
|
|
181
|
+
\connect app
|
|
182
|
+
GRANT USAGE ON SCHEMA public TO mcp_reader;
|
|
183
|
+
GRANT SELECT ON ALL TABLES IN SCHEMA public TO mcp_reader;
|
|
184
|
+
```
|
|
185
|
+
|
|
186
|
+
### Verify effective schema privileges
|
|
187
|
+
|
|
188
|
+
Before configuring the connection, verify that `mcp_reader` cannot create objects in the target schema:
|
|
189
|
+
|
|
190
|
+
```sql
|
|
191
|
+
SELECT has_schema_privilege('mcp_reader', 'public', 'CREATE') AS can_create_objects;
|
|
192
|
+
```
|
|
193
|
+
|
|
194
|
+
The result must be `false`. A result of `true` means the role is not restricted to read access in that schema. This can occur when an installation upgraded from PostgreSQL 14 or earlier retains a shared `PUBLIC` `CREATE` grant on `public`. Do not revoke a shared `PUBLIC` privilege solely for this server; have the database administrator decide the database-wide schema policy first.
|
|
195
|
+
|
|
196
|
+
The `\password` command prompts without placing the password in shell history. Store the resulting connection secret only in the runtime secret or environment manager, not in the repository. If the role must read tables created in the future and `postgres` creates those tables, run this optional command as `postgres`. Replace `postgres` with the actual object-creator role in other environments:
|
|
197
|
+
|
|
198
|
+
```sql
|
|
199
|
+
ALTER DEFAULT PRIVILEGES FOR ROLE postgres IN SCHEMA public
|
|
200
|
+
GRANT SELECT ON TABLES TO mcp_reader;
|
|
201
|
+
```
|
|
202
|
+
|
|
203
|
+
Before configuring the connection, connect as `mcp_reader` and verify that every boolean below is `false`:
|
|
204
|
+
|
|
205
|
+
```sql
|
|
206
|
+
SELECT current_user, rolsuper, rolbypassrls, rolreplication,
|
|
207
|
+
pg_has_role(current_user, 'pg_read_server_files', 'member') AS read_server_files,
|
|
208
|
+
pg_has_role(current_user, 'pg_write_server_files', 'member') AS write_server_files,
|
|
209
|
+
pg_has_role(current_user, 'pg_execute_server_program', 'member') AS execute_server_program,
|
|
210
|
+
pg_has_role(current_user, 'pg_signal_backend', 'member') AS signal_backend
|
|
211
|
+
FROM pg_roles
|
|
212
|
+
WHERE rolname = current_user;
|
|
213
|
+
```
|
|
214
|
+
|
|
215
|
+
If any value is `true`, use a new dedicated role rather than removing privileges from a shared administrator or application role.
|
|
216
|
+
|
|
38
217
|
## Read-only boundary and deployment risk
|
|
39
218
|
|
|
40
219
|
Each database operation uses a PostgreSQL read-only transaction and pgx's extended execution protocol. `postgres_query` is parsed as exactly one SELECT, rejecting DML, DDL, row locks, SELECT INTO, modifying CTEs, and selected PostgreSQL built-ins with known side effects.
|
|
@@ -74,7 +253,14 @@ The HTTP health endpoint is `GET /healthz`. See `config.example.yaml` for transp
|
|
|
74
253
|
|
|
75
254
|
```sh
|
|
76
255
|
make docker
|
|
77
|
-
docker run --rm -i
|
|
256
|
+
docker run --rm -i \
|
|
257
|
+
--env MCP_POSTGRES_HOST \
|
|
258
|
+
--env MCP_POSTGRES_PORT \
|
|
259
|
+
--env MCP_POSTGRES_DATABASE \
|
|
260
|
+
--env MCP_POSTGRES_USERNAME \
|
|
261
|
+
--env MCP_POSTGRES_PASSWORD \
|
|
262
|
+
--env MCP_POSTGRES_SSLMODE \
|
|
263
|
+
postgres-mcp-server:dev
|
|
78
264
|
```
|
|
79
265
|
|
|
80
266
|
The image entrypoint is `postgres-mcp-server mcp`.
|
package/package.json
CHANGED
|
@@ -1,17 +1,17 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@futuretea/postgres-mcp-server",
|
|
3
|
-
"version": "0.0
|
|
3
|
+
"version": "0.2.0",
|
|
4
4
|
"description": "Read-only PostgreSQL Model Context Protocol server",
|
|
5
5
|
"main": "./bin/index.js",
|
|
6
6
|
"bin": {
|
|
7
7
|
"postgres-mcp-server": "bin/index.js"
|
|
8
8
|
},
|
|
9
9
|
"optionalDependencies": {
|
|
10
|
-
"@futuretea/postgres-mcp-server-darwin-amd64": "0.0
|
|
11
|
-
"@futuretea/postgres-mcp-server-darwin-arm64": "0.0
|
|
12
|
-
"@futuretea/postgres-mcp-server-linux-amd64": "0.0
|
|
13
|
-
"@futuretea/postgres-mcp-server-linux-arm64": "0.0
|
|
14
|
-
"@futuretea/postgres-mcp-server-windows-amd64": "0.0
|
|
10
|
+
"@futuretea/postgres-mcp-server-darwin-amd64": "0.2.0",
|
|
11
|
+
"@futuretea/postgres-mcp-server-darwin-arm64": "0.2.0",
|
|
12
|
+
"@futuretea/postgres-mcp-server-linux-amd64": "0.2.0",
|
|
13
|
+
"@futuretea/postgres-mcp-server-linux-arm64": "0.2.0",
|
|
14
|
+
"@futuretea/postgres-mcp-server-windows-amd64": "0.2.0"
|
|
15
15
|
},
|
|
16
16
|
"repository": {
|
|
17
17
|
"type": "git",
|