Permite que agentes de IA realizem análises seguras e apenas de leitura em bancos de dados PostgreSQL com arquivos de contexto de schema compartilhados.
Também conhecido como contextflo/postgres-mcp, postgres-mcp, @contextflo/postgres-mcp
- Stars
- 4
- Ferramentas
- 4
- Downloads, 30 dias
- 937
- Versão mais recente
- 0.1.4
- Último commit
- 28 de set. de 2026
- Licença
- MIT
O que é o MCP Postgres (read-only)?
Permite que agentes de IA realizem análises seguras e apenas de leitura em bancos de dados PostgreSQL com arquivos de contexto de schema compartilhados. Ele expõe 4 ferramentas, como query, list_tables, get_table_context.
Resumo gerado a partir do README do projeto
Sobre o MCP server de Postgres (read-only)
Realizar análises seguras e apenas de leitura em bancos de dados PostgreSQL é o que este MCP server permite para desenvolvedores que utilizam agentes de IA. Ele oferece um ambiente altamente seguro ao aplicar restrições de apenas leitura através de quatro camadas independentes, incluindo a role do banco de dados e o parser do Postgres, o que evita vulnerabilidades de SQL injection encontradas em implementações mais antigas. Os usuários se conectam fornecendo uma string de conexão via argumento de linha de comando ou uma variável de ambiente DATABASE_URL.
Este servidor foi projetado para funcionar com ferramentas como Claude Code, Cursor e Claude Desktop. Ele utiliza um arquivo de contexto markdown compartilhado para garantir que a IA entenda lógicas de negócio específicas, como se uma coluna de receita representa valores brutos ou líquidos. O agente pode usar a ferramenta add_table_context para documentar novas descobertas diretamente neste arquivo para revisão humana. Para gerenciar o volume de dados e a performance, o servidor inclui um timeout padrão de 30 segundos para comandos e limita os resultados a 1000 linhas.
O que você pode fazer com ele
- 1Analisar o schema do banco de dados com contexto de negócioPeça a um agente de IA para explicar colunas específicas de tabelas usando as definições de negócio curadas e armazenadas no seu arquivo de contexto.
- 2Descobrir tabelas usando correspondência de padrõesPeça ao agente para encontrar todas as tabelas relacionadas a uma palavra-chave específica, como revenue.
Escrito a partir do README do projeto. Cada caso de uso é verificado com uma citação dele.
Como instalar o MCP Postgres (read-only)
Formatos verificados em 10 nov 2026Adicionar ao CursorAdicionar ao GooseInstalar o MCP Postgres (read-only) no Claude Code
$ claude mcp add --env 'DATABASE_URL=<YOUR_DATABASE_URL>' postgres-mcp -- npx -y @contextflo/postgres-mcpInstalar o MCP Postgres (read-only) no Cursor
~/.cursor/mcp.json
{
"mcpServers": {
"postgres-mcp": {
"command": "npx",
"args": [
"-y",
"@contextflo/postgres-mcp"
],
"env": {
"DATABASE_URL": "<YOUR_DATABASE_URL>"
}
}
}
}Instalar o MCP Postgres (read-only) no VS Code
.vscode/mcp.json
{
"servers": {
"postgres-mcp": {
"type": "stdio",
"command": "npx",
"args": [
"-y",
"@contextflo/postgres-mcp"
],
"env": {
"DATABASE_URL": "<YOUR_DATABASE_URL>"
}
}
}
}Instalar o MCP Postgres (read-only) no VS Code CLI
$ code --add-mcp '{"name":"postgres-mcp","type":"stdio","command":"npx","args":["-y","@contextflo/postgres-mcp"],"env":{"DATABASE_URL":"<YOUR_DATABASE_URL>"}}'Instalar o MCP Postgres (read-only) no Claude Desktop
claude_desktop_config.json
{
"mcpServers": {
"postgres-mcp": {
"command": "npx",
"args": [
"-y",
"@contextflo/postgres-mcp"
],
"env": {
"DATABASE_URL": "<YOUR_DATABASE_URL>"
}
}
}
}Instalar o MCP Postgres (read-only) no Codex
$ codex mcp add postgres-mcp --env 'DATABASE_URL=<YOUR_DATABASE_URL>' -- npx -y @contextflo/postgres-mcpInstalar o MCP Postgres (read-only) no Codex config.toml
~/.codex/config.toml
[mcp_servers.postgres-mcp] command = "npx" args = ["-y", "@contextflo/postgres-mcp"] [mcp_servers.postgres-mcp.env] DATABASE_URL = "<YOUR_DATABASE_URL>"
Instalar o MCP Postgres (read-only) no Gemini CLI
$ gemini mcp add -s user -e 'DATABASE_URL=<YOUR_DATABASE_URL>' postgres-mcp npx -- -y @contextflo/postgres-mcpInstalar o MCP Postgres (read-only) no Gemini settings.json
~/.gemini/settings.json
{
"mcpServers": {
"postgres-mcp": {
"command": "npx",
"args": [
"-y",
"@contextflo/postgres-mcp"
],
"env": {
"DATABASE_URL": "<YOUR_DATABASE_URL>"
}
}
}
}Ferramentas do MCP Postgres (read-only) 4
Detectadas a partir do READMEquerylist_tablesget_table_contextadd_table_context
| query | — | |
| list_tables | — | |
| get_table_context | — | |
| add_table_context | — |
Configuração
DATABASE_URLObrigatórioSecretoPostgres connection string. Use a read-only role.
TEST_DATABASE_URL
| Nome | Descrição | Tipo |
|---|---|---|
| DATABASE_URL | Postgres connection string. Use a read-only role. | ObrigatórioSecreto |
| TEST_DATABASE_URL | — |
Verificações automatizadas
Executado em 13 de nov. de 2026Relatório completo →Passou em nossas verificações automatizadas. Isso não é uma auditoria de segurança: leia o código e dê ao servidor o acesso mais restrito de que ele precisa. Como as verificações funcionam
- Repositório de origem vinculado e acessívelcontextflo/postgres-mcp is public and reachablegithub.com/contextflo/postgres-mcp ↗Passou
- O pacote indica este repositório como sua origem@contextflo/postgres-mcp names contextflo/postgres-mcp as sourcenpmjs.com/package/@contextflo/postgres-mcp ↗Passou
- Proveniência da build (atestação Sigstore)Sigstore attestation for @contextflo/postgres-mcpnpmjs.com/package/@contextflo/postgres-mcp/v/0.1.4#provenanc ↗Passou
- Licença de código aberto (OSI)MITspdx.org/licenses/MIT.html ↗Passou
- Commit ou release no último anoLast commit or release 2026-09-28github.com/contextflo/postgres-mcp ↗Passou
- OpenSSF ScorecardNão verificado
- Nome do pacote não é próximo a um pacote popularNo popular package one edit away from @contextflo/postgres-mcpPassou
- Nenhum aviso crítico no pacote ou em suas dependências116 resolved dependencies checked; no critical advisoryosv.dev ↗Passou
- Sem instruções ocultas para o modelo4 tool descriptions and the README read; no override phrases, credential paths or hidden charactersPassou
- Ferramentas destrutivas estão rotuladasNo tool named like delete, drop or execPassou
- O endpoint remoto responde ao handshake do MCPNão verificado
README
Ver no GitHub@contextflo/postgres-mcp
The analytics MCP server for Postgres. Read-only by construction, with a context file you and the agent both write to, so the model answers the way your team would.
Built and maintained by Contextflo.
A drop-in replacement for the archived @modelcontextprotocol/server-postgres, which shipped with a
SQL injection vulnerability
that let COMMIT; DROP SCHEMA public CASCADE walk straight out of its read-only transaction.
Watch the 100-second demo: setup, the
agent working out that an events table is not what it looks like and saving that as a note, and a DROP the server
refuses.
npx @contextflo/postgres-mcp postgresql://localhost/mydb
Why this one
Read-only that holds up. The archived server enforced read-only as a property of the SQL string. Here it is a property of the wire protocol, the connection, the Postgres parser, and the database role: four independent layers, each of which stops that payload on its own. The exploit is a test case in this repo.
Answers that make sense. A model that does not know fct_orders_v2 is the table your team actually uses, or that
revenue is gross rather than net, writes confident, wrong SQL. .contextflo/context.md is a markdown file you edit
and this server hands to the model, with nothing behind it but the file. The agent adds to it too: when it learns
something the schema does not say, add_table_context appends a note, which you review in a diff like any other change.
Setup
1. Create a read-only role. Run this as the database owner, in psql or your provider's SQL editor. Use your
database name and a real password, and repeat the schema lines for each schema the agent should see:
CREATE ROLE mcp_readonly LOGIN PASSWORD 'change-me';
GRANT CONNECT ON DATABASE mydb TO mcp_readonly;
GRANT USAGE ON SCHEMA public TO mcp_readonly;
GRANT SELECT ON ALL TABLES IN SCHEMA public TO mcp_readonly;
ALTER DEFAULT PRIVILEGES IN SCHEMA public GRANT SELECT ON TABLES TO mcp_readonly;
This makes read-only a property of the database, not just of this server's code.
2. Put that role's connection string in .env in your project folder:
DATABASE_URL='postgresql://mcp_readonly:change-me@db.example.com:5432/mydb'
Keep the quotes: hosted providers add ?sslmode=require&..., and the & needs them. The server reads DATABASE_URL
from .env in the directory it starts in, so the connection string never appears on a command line.
Point it at a read replica or a branch rather than your primary if you can. Read-only stops writes, not load: an agent
exploring your data can run a full-table scan or a heavy join, and on the primary that competes with your application.
Neon and Supabase can branch or replicate a database in a few clicks, and RDS, Cloud SQL, and most other hosts offer
read replicas. The statement timeout (30 seconds by default, --statement-timeout) and the row cap limit how long one
query runs and how much it returns; they do not make it cheap.
3. Generate the context file:
npx @contextflo/postgres-mcp init
That writes .contextflo/context.md, seeded from your COMMENT ON values. Edit it: the business definitions section
is where the value is.
4. Add it to your client. Claude Code starts servers in your project folder, so it finds .env and the context
file on its own:
claude mcp add postgres --scope project -- npx -y @contextflo/postgres-mcp
--scope project writes .mcp.json into the folder instead of your global config.
Other clients may start servers outside your project folder (Claude Desktop starts them in /), so give them the
connection string and the context file explicitly:
{
"mcpServers": {
"postgres": {
"command": "npx",
"args": ["-y", "@contextflo/postgres-mcp", "--context-file", "/path/to/project/.contextflo/context.md"],
"env": { "DATABASE_URL": "postgresql://mcp_readonly:change-me@db.example.com:5432/mydb" }
}
}
}
Cursor uses .cursor/mcp.json. Claude Desktop uses claude_desktop_config.json (macOS:
~/Library/Application Support/Claude/, Windows: %APPDATA%\Claude\). VS Code uses .vscode/mcp.json, with
servers in place of mcpServers.
Tools
| Tool | What it does |
|---|---|
query |
Runs one read-only statement: SELECT, WITH ... SELECT, EXPLAIN, or SHOW. |
list_tables |
Lists readable tables with descriptions. pattern matches anywhere in the name or description. |
get_table_context |
Describes tables: columns, types, keys, foreign key targets, enum values, curated descriptions. |
add_table_context |
Lets the agent write down a gotcha it found (amount is in cents, status has an undocumented value) in the context file. |
There is no separate search tool, and that is deliberate. information_schema and pg_catalog are ordinary tables,
so anything more specific, like finding every column named like %revenue% or listing tables with no primary key,
is a query the model can write itself:
SELECT table_schema, table_name, column_name
FROM information_schema.columns
WHERE column_name ILIKE '%revenue%';
Table schemas are also exposed as postgres://<host>/<table>/schema resources, matching the archived server, for
anything pinned to those URIs. Most clients never fetch resources on their own, which is why discovery lives in the
tools.
How read-only is enforced
Four layers. Each one stops the archived server's exploit by itself.
1. Extended query protocol. User SQL goes through pg-cursor, which always issues Parse/Bind/Execute, so
Postgres itself rejects multi-statement input. The archived server called client.query(sql) with a bare string;
node-postgres only prepares a statement when there are bind values, so that took the simple protocol path, where
; separates statements. That is the whole bug.
2. Connection-level read-only. default_transaction_read_only=on is set in the startup packet, and every
statement runs inside an explicit BEGIN READ ONLY that always ends in ROLLBACK, never COMMIT. The rollback
also undoes any SET made inside the transaction, so a statement cannot leave a pooled connection weakened for
whoever gets it next.
3. A statement allowlist on the real Postgres parser. libpg-query
is the actual Postgres C parser compiled to WASM, not a JavaScript approximation of SQL. The whole parse tree is
walked rather than just the top-level node, which is what catches a data-modifying CTE:
WITH x AS (INSERT INTO users VALUES (1) RETURNING *) SELECT * FROM x
That parses as a SelectStmt. A validator checking only the statement type runs it. Unknown node types fail closed.
Functions are checked against the database's own catalog. Postgres labels every function immutable, stable, or
volatile, and only volatile ones can have side effects, so a volatile function is refused unless it is on a short list
of harmless ones analysis needs (random(), clock_timestamp(), the table size functions). That covers dblink,
pg_logical_emit_message (which writes to the WAL even in a read-only transaction), advisory locks, statistics resets,
and whatever a future Postgres adds, without anyone having to name them. SECURITY DEFINER functions, which run with
their owner's privileges, are refused whatever their label. A fixed list of known escapes is checked as well.
4. A read-only database role. The layers above are code, and code has bugs. A role that cannot write is enforced
by Postgres regardless, which is why creating one is the first step of Setup. The server warns on startup
if you connect as a superuser, and init prints the role snippet if the role it connects as can write.
What this does not protect against. The function check sees the functions a query calls directly, and it trusts
how each is labelled. A user-defined function declared STABLE that writes anyway is allowed, and so is a function
reached indirectly: inside a view, behind an operator, or through a type cast. The read-only transaction still refuses
anything that changes table data that way; what can slip through is the rarer kind of side effect, such as a message
written to the WAL. Layer 4 is what stops those, which is why the read-only role is the recommended setup rather than
an optional extra. Read-only is also not
confidentiality: anything the connected role can read, a model can read, so grant it only what you want an agent
to see.
Migrating from @modelcontextprotocol/server-postgres
Swap the package name. The tool is still called query, still takes sql, still returns JSON rows, and the
connection string is still the first argument.
Four deliberate differences:
- Multi-statement SQL and
SET/RESETare rejected with a clear error. On the archived server these "worked", and that was the vulnerability. - Results are capped at 1000 rows and 50,000 characters by default, and single values over 2,000 characters are shortened. Truncation is stated in the output, never silent. Rows come back one per line rather than pretty-printed, which roughly halves their token cost; it is still a JSON array. Dates and timestamps are exactly what Postgres sent, not re-rendered in the server's timezone.
- Schema discovery is a tool, not just a resource. Most clients do not auto-attach resources, which is why models using the old server so often did not know the schema.
- All non-system schemas are visible, not only
public, and column descriptions come through fromCOMMENT ON.
Options
--max-rows <n> Maximum rows returned per query (default: 1000)
--max-output-chars <n> Character budget for one query result (default: 50000)
--statement-timeout <ms> Server-side statement timeout (default: 30000)
--context-file <path> Curated schema context (default: .contextflo/context.md)
--no-context-writes Do not offer add_table_context; the context file is only read
--log-file <path> Query audit log (default: .contextflo/log.md once that directory exists)
--no-log Never write a query log
--http Serve over streamable HTTP instead of stdio
--port <n> HTTP port (default: 8080)
--host <addr> HTTP bind address (default: 127.0.0.1)
DATABASE_URL supplies the connection string if you do not pass one, from the environment or from .env in the
current directory. The server connects on first use: without a connection string it still starts and lists its tools,
and each tool call says what is missing. AUTH_TOKEN, with --http, requires that
value as a bearer token.
Connection poolers. PgBouncer (and so the pooled connection strings from Supabase, Neon, and others) refuses
the startup parameters this server normally sends. When that happens it reconnects without them and says so on
stderr. Nothing is weakened: every statement still runs in BEGIN READ ONLY with its own statement timeout, and CI
runs the read-only suite through PgBouncer in transaction mode.
The context file
# Database context
Revenue means gross, before refunds.
"Active customer" means an order in the last 90 days.
## Tables
### public.orders
One row per customer order. Source of truth for revenue, not `orders_legacy`.
- revenue_usd: Gross revenue, before refunds. Net lives in `order_refunds`.
- status: One of pending, paid, refunded.
Everything above ## Tables is handed to the model: as server instructions, and again at the top of list_tables,
because several clients never show the model server instructions. HTML comments are left out. Under ## Tables, a
### heading names a table, the prose beneath describes it, and - column: meaning lines describe columns (a dash
separator works too). Your text wins over COMMENT ON. Edits take effect on the next tool call; no restart.
A relative --context-file resolves against the directory the client starts the server in. Claude Desktop starts
servers in /, so there it falls back to your home directory (~/.contextflo/context.md). For a file that lives in
a repo, pass an absolute path. The server prints the path it is using on startup.
The agent adds to it. When the model finds something the schema does not say (amount is in cents, status
also holds 'void' on old rows, every query needs deleted_at IS NULL), add_table_context appends it to this file,
and every later session starts knowing it. Notes are only ever appended, never substituted for what you wrote, and
only for tables and columns that exist. Treat them like any other change: keep the file in git and read the diff. A
model can be wrong, and text inside your data can steer what it writes, so a note is a suggestion until someone has
looked at it. --no-context-writes turns the tool off.
init seeds this from existing comments, and only for columns that already have one. A file with a blank
placeholder for all 4000 columns is a file nobody edits.
Richer context generated from your code and docs, and shared across a team, is what contextflo.com does.
Query log
Once .contextflo/ exists, every statement is appended to .contextflo/log.md with its outcome, row count, and
duration. It is written for you, not fed back to the model. --no-log turns it off.
Docker
docker run -i --rm ghcr.io/contextflo/postgres-mcp postgresql://host.docker.internal/mydb
For a remote endpoint, see docker-compose.example.yml. Note what you are doing
before you bind 0.0.0.0: that is a live database connection on a port. Set AUTH_TOKEN, keep it inside a private
network, and terminate TLS in front of it, because the token is plaintext on the wire otherwise. The server prints a
warning when it is exposed without a token.
On the default loopback bind, requests whose Host or Origin is not local are refused. That is what stops a web
page from using DNS rebinding to reach a server on 127.0.0.1 through your browser.
Development
npm install
npm run build
npm test
npm run db:up # throwaway Postgres for the integration suite (needs Docker)
TEST_DATABASE_URL=postgres://postgres:postgres@localhost:55432/postgres npm test
npm run db:down
The integration suite deliberately bypasses the parser and drives the database directly, so it proves the wire and
transaction layers rather than the validator. It skips without TEST_DATABASE_URL and is required to run in CI.
Security
Please report vulnerabilities privately. See SECURITY.md.
License
MIT
Perguntas sobre o MCP Postgres (read-only)
Como adiciono o MCP Postgres (read-only) ao Claude Code?
Execute claude mcp add --env 'DATABASE_URL=<YOUR_DATABASE_URL>' postgres-mcp -- npx -y @contextflo/postgres-mcp no seu terminal. Adicione --scope user para torná-lo disponível em todos os projetos.
Como adiciono o MCP Postgres (read-only) ao Cursor?
Abra ~/.cursor/mcp.json e adicione o servidor em mcpServers, usando a configuração do Cursor mostrada na seção de instalação acima.
Quais ferramentas o MCP Postgres (read-only) oferece?
Ele expõe 4 ferramentas, incluindo query, list_tables, get_table_context, add_table_context.
Como a restrição de apenas leitura é aplicada?
Ela é aplicada por meio de quatro camadas independentes: o protocolo de consulta estendido, configurações de apenas leitura no nível da conexão, uma lista de permissões de comandos (allowlist) usando o parser C do Postgres e uma role de banco de dados dedicada apenas para leitura.
O agente de IA pode atualizar o contexto do schema do banco de dados?
Sim, o agente pode usar a ferramenta add_table_context para adicionar notas sobre o schema a um arquivo de contexto em markdown, que pode então ser revisado por um humano.
O que acontece se uma consulta for muito grande ou demorar muito?
O servidor inclui um timeout padrão de 30 segundos para comandos e limita os resultados a 1000 linhas e 50.000 caracteres para evitar o uso excessivo de recursos.
Como configuro o servidor com uma string de conexão?
Você pode fornecer a string de conexão como um argumento de linha de comando ou definir uma variável DATABASE_URL em um arquivo .env no diretório do seu projeto.