A Monday numbers brief
Prompt
Every Monday at 8:00, query the database for last week's signups, orders, and cancellations, compare each number to the week before, and write me a short note with the three numbers and whether each went up or down.
Verified MCP server: PostgreSQL
The Postgres MCP server, verified live on a real Mac.
- Verified2026-08-03macOS 26.3.1
- Package@modelcontextprotocol/server-postgres 0.6.2
- Self-reportedexample-servers/postgres 0.1.0
- MCP protocol2024-11-05
- RuntimeNode v24.18.0
The short answer
Last verified 2026-08-03
The postgres MCP server is the reference database server of the Model Context Protocol project: it connects an AI assistant to a PostgreSQL database and hands it exactly one tool, a read-only SQL query. It is also deprecated. npm has served the same release since December 2024 and prints a "no longer supported" warning when you install it, and the source now lives in an archived repository, yet the package was still downloaded about 124,000 times last week. So we ran it. We pointed it at a scratch database we seeded on this Mac, spoke the protocol to it, read real rows back, then tried to write and watched it refuse. The raw output is on this page, including every error message, and a maintained alternative is named below if you need one. [1][2][3][4]
Verification
How this MCP server was verified.
Method
We spawned the server with npx over stdio, pointing it at a scratch PostgreSQL 16 database we seeded on this Mac for the test, never at real data. We completed the MCP initialize handshake, called tools/list, then made real query calls: one successful read of three rows, and a set of deliberate failures to capture the exact error text the server returns. The tool table below is that capture, word for word. Two details we are not smoothing over: the server answered our 2025-06-18 handshake with the older protocol revision 2024-11-05, and it printed nothing of its own on stderr, so the banner below is npm warning us that the package is deprecated, which it does on the first install and not on cached runs.
Startup banner
npm warn deprecated @modelcontextprotocol/server-postgres@0.6.2: Package no longer supported. Contact Support at https://www.npmjs.com/support for more info.
One real tool call
tools/call query {"sql": "SELECT book, author, pages FROM reading_log ORDER BY id LIMIT 3"}[
{
"book": "The Mythical Man-Month",
"author": "Frederick Brooks",
"pages": 322
},Real lines from the captured result: enough to prove the call answered.
Tools
Every tool, enumerated from the running server.
The server answered tools/list with 1 tools on 2026-08-03. The names, descriptions and parameters below are its own words, copied from that response and never edited.
| Tool | What it does |
|---|---|
| querysql | Run a read-only SQL query |
Parameters marked with * are required.
Setup
Working configs, one per app.
Copy the block for the app you use. Each one is the configuration this server was verified with.
Claude Desktop
Open the file ~/Library/Application Support/Claude/claude_desktop_config.json (in Claude Desktop: Settings, then Developer, then Edit Config) and add:
{
"mcpServers": {
"postgres": {
"command": "npx",
"args": [
"-y",
"@modelcontextprotocol/server-postgres",
"postgresql://yourname@localhost:5432/yourdb"
]
}
}
}The last argument is your connection string, and it is the only thing you need to change. Read it left to right: postgresql:// is fixed, yourname is the database user, localhost is the machine the database runs on, 5432 is the port PostgreSQL uses by default, and yourdb is the database name. If your user needs a password it goes after the name, as postgresql://yourname:yourpassword@localhost:5432/yourdb. Quit and reopen Claude Desktop afterwards. [9]
Claude Code
One command in your terminal:
claude mcp add postgres -- npx -y @modelcontextprotocol/server-postgres postgresql://yourname@localhost:5432/yourdb
Everything after the double dash is the exact command Claude Code will run. Swap the connection string for your own user, host, port and database name. Note that the string lands in a config file in plain text, so if it carries a password, treat that file the way you treat any other file holding one. [10]
Cursor
Add to ~/.cursor/mcp.json for every project, or to .cursor/mcp.json inside one project:
{
"mcpServers": {
"postgres": {
"command": "npx",
"args": [
"-y",
"@modelcontextprotocol/server-postgres",
"postgresql://yourname@localhost:5432/yourdb"
]
}
}
}Same connection string as above, same five parts. Cursor picks the file up on restart. [11]
Routines
No JSON file and no terminal. In Routines: Settings, then Assistant, then Connections, then Add MCP Server. Switch the form to Command (stdio) and enter:
Name PostgreSQL Command npx Arguments -y @modelcontextprotocol/server-postgres postgresql://yourname@localhost:5432/yourdb
The Arguments field splits on spaces, which a connection string normally has none of. If a password contains a space or a punctuation character, URL-encode it first. Click Test Connection: a working server answers with its tool count, one for this server. Read the walkthrough below before you trust that result, because it proves less than it looks like it does. [12]
No terminal needed
Set the PostgreSQL MCP server up without the terminal.
If you have never opened Terminal and never want to, this is your path. Routines is a Mac app that runs MCP servers for you: fill in three fields once, and this server's tool is available to your AI in chat and in scheduled routines.
01
Install Routines
Download the app from getroutines.ai/download, drag it to Applications, and sign in.
02
Open the MCP settings
Click your account at the bottom of the sidebar and choose Settings. Open the Assistant section, then the Connections tab, scroll to MCP Servers, and click Add MCP Server.
03
Choose Command (stdio)
Switch the form to Command (stdio): this server is a command your Mac runs, not a web address it calls.
04
Build your connection string
Name: PostgreSQL. Command: npx. Arguments: -y @modelcontextprotocol/server-postgres followed by a space and your connection string. The string has five parts: postgresql://, the database user, the host, the port, and the database name, as in postgresql://yourname@localhost:5432/yourdb. If you did not set the database up yourself, whoever did can give you all five, and it is worth asking them for a read-only user while you are there.
05
Test, then add
Leave Environment Variables empty, this server reads everything from the arguments. Click Test Connection: Routines starts the server and reports how many tools it found, one for this one. Now the part nobody writes down: the server does not open the database until the first real query, so a connection string with the wrong database name still passes this test. A passing test proves the server started, not that it can reach your data. Click Add Server, then ask it something in chat to confirm the connection.
06
Use it
The tool works in chat right away. To let a scheduled routine use it, open the routine, find the Tools & connections card, and tick the server under Apps.
Routine ideas
Routines worth scheduling.
Once the server is connected, a scheduled routine can use its tools while you are away. Copy a prompt, paste it into Routines, and pick a time.
A quiet data check
Prompt
Every weekday at 7:00, run my usual read-only checks against the database: rows added yesterday, records missing an email address, and the oldest item still unprocessed. Only message me if one of them looks wrong.
A month-end summary
Prompt
On the first of every month at 9:00, pull last month's totals by category from the database and save them as a markdown table in month-end.md, with the previous month in a second column for comparison.
Troubleshooting
The errors we hit, and what fixed them.
Real errors captured during the verification run, printed exactly as the server returned them.
Every attempt to change data is rejected
What you see
cannot execute INSERT in a read-only transaction
The fix
Working as designed, and it is the whole point of this server. Before running your SQL it opens a transaction with BEGIN TRANSACTION READ ONLY and rolls it back afterwards, so PostgreSQL itself refuses anything that writes. We tried an INSERT and got the line above; an UPDATE returns the same sentence with the verb swapped, cannot execute UPDATE in a read-only transaction. There is no flag or argument that turns this off. If you need an assistant that can write, this is the wrong server and you want the maintained alternative named in the questions below.
Test Connection passes but every query fails
What you see
database "does_not_exist_db" does not exist
The fix
This is the trap we hit, so it is worth spelling out. The server does not touch the database at startup: it starts, reports its one tool, and passes your client's connection test with a connection string pointing at a database that is not there. The mistake only surfaces on the first real query, as the line above. Check the database name at the end of your connection string, then the user, host and port, and confirm the same string works with a normal PostgreSQL client. Always follow a passing connection test with one real question.
The assistant says a table is missing that you know exists
What you see
relation "books" does not exist
The fix
PostgreSQL is telling you the table is not visible to this connection. Three usual causes: the name is different from what you remember, the table lives in a schema that is not on the search path, so it needs to be written as schemaname.books, or the user in your connection string cannot see it. Ask the assistant to list the tables it can actually see before asking it about one by name.
A query comes back as a syntax error
What you see
syntax error at end of input
The fix
The SQL reached PostgreSQL incomplete. We triggered this on purpose by sending a statement ending in ORDER with nothing after it. When an assistant writes the SQL, this usually means it produced a truncated statement, so ask it to show you the query it ran and try again. The error text names the position PostgreSQL choked at, which is the fastest way to find the gap.
The server exits at once and your client hangs
What you see
Please provide a database URL as a command-line argument
The fix
You started it with no connection string. Unlike some MCP servers, this one prints that single line and quits, so the client is left waiting for a handshake that never arrives and eventually times out rather than showing you a useful message. Add your connection string as the last argument, after the package name, and restart the client.
Your MCP client cannot start the server at all
The fix
The npx command belongs to Node.js. If Node is not installed on your Mac, every client on this page fails at the spawn step before the server can say anything. Install Node from nodejs.org, restart your MCP client, and try again.
FAQ
Questions people ask.
What is the postgres MCP server?
It is the reference PostgreSQL server of the Model Context Protocol project. Once connected, an AI assistant such as Claude can run SQL against a database you point it at and read the answers back, which is what lets you ask questions about your data in plain English instead of writing queries. It runs as a local process on your Mac and talks to your AI app over stdio. [4][3]
Is the postgres MCP server still maintained?
No, and you should know that before you install it. npm marks the package deprecated with the note "Package no longer supported", the newest release is 0.6.2 from December 2024, and the source moved into a repository the project archived and labelled "Reference MCP servers that are no longer maintained". It was still downloaded about 124,000 times last week, and it ran correctly for us on 2026-08-03, which is the tension worth naming: widely used, plainly unmaintained. Its age shows in small ways, such as answering our 2025-06-18 handshake with the older protocol revision 2024-11-05. Working today is not a promise about next year, so if this is going into something you depend on, read the alternative below first. [1][2][3]
What tools does the postgres MCP server include?
Exactly one, named query, described by the server as "Run a read-only SQL query". It takes a single sql parameter. One detail we found on the wire and did not expect: the tool's schema declares that parameter but never lists it as required, so a client is free to call the tool without it, and when we did the server answered "Client was passed a null or undefined query". In practice your assistant always sends SQL, so this is a curiosity rather than a problem. The server also advertises MCP resources, which is how it offers each table's schema for browsing; we enumerated tools on this run, not resources. [4]
Can the postgres MCP server change my data?
No, and we tested the fence rather than trusting it. The server wraps every query in BEGIN TRANSACTION READ ONLY and rolls it back, so PostgreSQL rejects writes itself: our INSERT and UPDATE attempts both came back refused, with the exact messages printed in the troubleshooting section above. Read-only is not the same as harmless, though. It can read every table the user in your connection string can read, and hand the contents to an AI model, so give it a user with access to what you actually want it to see and nothing more. [4]
Is there a maintained alternative?
Yes. postgres-mcp from CrystalDBA, published on PyPI, is at version 0.3.0, describes itself as a PostgreSQL tuning and analysis tool, is MIT licensed, and its repository was last updated in January 2026 rather than archived, with about 3,100 stars and roughly 107,000 downloads in the last week. It offers configurable read and write access, which the reference server deliberately does not. We have not run it, so it gets no badge here: this page verifies the reference server and only reports what the registries say about the alternative. [6][7][8]
Do I need the terminal to set it up?
No. In Routines you fill three fields in Settings and click Test Connection; the walkthrough above shows every click, including the one warning that matters, which is that a passing connection test does not prove your connection string reaches the right database. Claude Desktop needs a small JSON file edited once. Only Claude Code is terminal-first by nature. [12][9]
Which apps can use the postgres MCP server?
Any MCP client that can launch a local stdio server: Claude Desktop, Claude Code, Cursor, and Routines all can, and the exact config for each is above. The server itself is the same in every client; only the place you paste the config differs. The connection string is the same in all four as well, which makes it easy to test in one client and copy across. [9][10][11][12]
Sources
Every external claim, receipted.
Anything on this page we did not observe in the run is linked here, with the date we read it. The run itself is the receipt for the rest.
[1]
npm registry: @modelcontextprotocol/server-postgresaccessed 2026-08-03Latest version 0.6.2, published 2024-12-04, carrying the deprecation notice "Package no longer supported. Contact Support at https://www.npmjs.com/support for more info." License MIT.
[2]
[3]
GitHub: modelcontextprotocol/servers-archivedaccessed 2026-08-03Archived repository described as "Reference MCP servers that are no longer maintained", last pushed 2025-05-28, per the GitHub API. It holds src/postgres.
[4]
Postgres server source: src/postgres/index.tsaccessed 2026-08-03Runs BEGIN TRANSACTION READ ONLY before each query and ROLLBACK after, with no flag to disable it: the only command-line argument it reads is the database URL, and it exits when that is missing. Instantiates StdioServerTransport, and serves each table's schema as an MCP resource.
[5]
modelcontextprotocol/servers-archived LICENSE fileaccessed 2026-08-03MIT, per the GitHub API license endpoint for the repository.
[6]
[7]
[8]
GitHub: crystaldba/postgres-mcpaccessed 2026-08-033,146 stars, MIT licensed, not archived, last pushed 2026-01-22, per the GitHub API. Described as providing "configurable read/write access and performance analysis".
[9]
modelcontextprotocol.io: Connect to local MCP serversaccessed 2026-08-03The official Claude Desktop quickstart and the claude_desktop_config.json shape.
[10]
[11]
[12]
Routines: Connectorsaccessed 2026-08-03How Routines runs one-click OAuth connectors and any MCP server.
This page describes PostgreSQL as it behaved in one dated run on one Mac. Versions move: if something here no longer matches what you see, the capture date at the top says how old the reading is.
Behind this directory
Routines, the app behind this directory, runs MCP servers like this one without a terminal: see how connectors work. Your notes stay markdown files on your Mac, there is no cloud bill, and it works offline. Download Routines