Read-only unless you say so
Every query runs in a read-only transaction. Changes need the switch turned on and a user that isn't a superuser.
BEGIN READ ONLYAccess modes and guardrails →A guided tour · about 5 minutes
Ask your Postgres database anything, in plain English.
NexQL MCP connects your AI app to your database. It runs on your computer, reads by default, and masks personal data before results reach the AI. This tour takes you from nothing to your first answer, one stop at a time.
Which app do you want to talk to your database from?
The rest of the tour changes to match. You can come back and switch at any time.
Touring with Claude Desktop.Your app needs to support local (stdio) MCP servers. Most desktop and editor apps do. ChatGPT chat doesn't yet; for Codex in the ChatGPT desktop app, pick Codex.
Next stop InstallInstall it like any app.
One file. No terminal, no Node, no config files.
Download for macOS (Apple silicon)
Not your computer? Pick another:
- Double-click the downloaded
.mcpbfile. Claude Desktop opens an install dialog. - No dialog? In Claude Desktop, open Settings → Extensions and drop the file there.
- Keep the dialog open. It asks for your database next, which is the next stop.
Nothing to install, really.
Claude Desktop starts NexQL through npx, which fetches the latest version when it's needed. You only need Node.js 18 or newer. Check with:
$ node --versionPrints v18 or higher? You're set. Otherwise install Node.js fromnodejs.org (the LTS version), then reopen your terminal.
Point it at your database.
First, find your database's address. Where does it live?
Where to lookUse localhost and the port Postgres listens on (5432 unless you changed it). For Docker, use the port you published, e.g. -p 5433:5432 means 5433.
Can your computer reach it?Nothing to open up. Postgres only needs to accept TCP connections, which it does by default.
Where to lookIn your project, open Connect at the top of the dashboard and copy the session pooler connection string.
Can your computer reach it?Reachable from anywhere by default. Use the session pooler if your network has no IPv6.
Where to lookIn the Neon console, click Connect on your project dashboard and copy the connection string.
Can your computer reach it?Reachable from anywhere by default. The string already includes sslmode=require.
Where to lookIn the RDS console, open your database and copy the endpoint and port from Connectivity & security.
Can your computer reach it?Your computer must be allowed in: the instance needs public access, and its security group an inbound rule for your IP on port 5432. Or connect over your VPN or a bastion.
Where to lookThe simplest route is the Cloud SQL Auth Proxy: run it on your computer and connect to 127.0.0.1. Otherwise use the instance's public IP from its Overview page.
Can your computer reach it?With the proxy, nothing to open up. With a public IP, add your IP under Connections → Authorized networks and use sslmode=require.
Where to lookIn the Azure portal, open your flexible server and copy the server name from Overview.
Can your computer reach it?Add a firewall rule for your IP under Networking. Azure requires SSL.
Where to lookOpen your service in the Timescale console and copy the connection details from its overview.
Can your computer reach it?Reachable from anywhere unless you set up IP allow lists.
Where to lookAsk whoever runs the database for the host, port, database name and a user. A user that can only read is best.
Can your computer reach it?Your computer needs to reach that host and port. A VPN or SSH tunnel counts.
Build the address
Fill in what you found. There's deliberately no password box: type your real password only into your app or NexQL's own page on your computer, never into a website, including this one.
postgres://app_reader:YOUR_PASSWORD@localhost:5432/appdb
Fill in Claude Desktop's dialog
Database URLpostgres://app_reader:your-real-password@localhost:5432/appdbPaste the address, then replace YOUR_PASSWORD here, in the dialog.
Allow changes to dataLeave it off. Claude can then only read.
Schemaspublic,salesOptional. Leave empty to let Claude see every schema.
Click Install, then make sure the extension is switched on. Claude Desktop keeps the URL in your system's secure storage.
Save it with NexQL's setup page
Run this in a terminal. A page opens on your computer (127.0.0.1), not on the web.
$ npx -y nexql-mcp@latest setup- Add a database with the details above, type the password on that page, and click Test. NexQL keeps the password in your system keychain.
- Open Clients, tick Claude Desktop and click Apply.
- Open Clients and copy the snippet for your app, or use the JSON below.
- Restart Claude Desktop so it picks NexQL up.
Prefer the terminal? Two commands do the same.
$ npx -y nexql-mcp@latest profile add mydb --url 'postgres://app_reader@localhost:5432/appdb' --access-mode read # asks for the password without showing it
$ npx -y nexql-mcp@latest init claude-code --apply
Then add this to your app's MCP settings:
{
"mcpServers": {
"nexql": {
"command": "npx",
"args": ["-y", "nexql-mcp@latest", "--profile", "mydb"]
}
}
}Now just ask.
Open a new chat in Claude Desktop and ask a question about your data. Here's what happens behind the answer.
Claude Desktop
Which products sold best last month?
search_schema "products sold" → orders.order_items, catalog.products
describe_object orders.order_items → 8 columns
run_select read-only → 5 rows · 41 ms
Your top seller last month was the Trail Runner 2, well ahead of the rest:
| Product | Units | Revenue |
|---|---|---|
| Trail Runner 2 | 1,284 | $153,951 |
| Merino Base Layer | 906 | $62,514 |
| Summit Pack 30L | 512 | $58,880 |
- Finds the right tables by searching an index of your schema kept on your computer, so it doesn't guess names.
- Reads the exact columns before writing any SQL.
- Runs a read-only query. Statements that change data are refused unless you allowed them.
- Masks personal data such as emails and phone numbers before the rows reach the AI.
Good first questions
- What's in this database?
- Which tables hold customer orders, and how are they linked?
- How much revenue did we make each month this year?
- Show me five example rows from the orders table.
- Why is this query slow? SELECT … (paste it)
More than one database? Just ask for it.
Tell your assistant where the other database is. NexQL opens a page on your computer where you type its password. Your assistant never sees it.
- 1 · You ask
Also connect our billing database: db.internal, database billing, user billing_reader.
add_database billing → page opened
- 2 · You confirm, on your computer
Connect "billing"
- Host
- db.internal
- Database
- billing
- User
- billing_reader
- Access
- Read-only
- 3 · It's connected
add_database → connected, read-only
billing is connected. Paid invoices total $64,844 across 1,200 invoices.
Why it's safeThe page lives on 127.0.0.1, works once, and expires after 10 minutes. You check the host and user before typing anything. New databases are always read-only.
Then ask across them"Compare last month's orders in shop with paid invoices in billing." Your assistant picks the right database for each part.
Never paste a password into the chat. Chats are stored by your AI provider. If you already did, change that password.
Setting several up at once? npx -y nexql-mcp@latest setup lets you add each database, then tick which ones Claude Desktop should see under Clients.
You stay in control.
What NexQL does by default, so you can let your assistant explore without worrying.
Personal data is masked
Columns that look like emails, phone numbers, names, addresses or secrets come back as <redacted>.
email → <redacted>What gets masked →Passwords stay on your computer
NexQL stores them in your system keychain, or an encrypted file where there isn't one. Never in plain text.
credential_provider = "keyring"Where passwords live →You know what leaves
NexQL runs locally and talks to your database directly. The tables it describes and the rows it returns become part of your chat, so your AI provider sees them.
127.0.0.1 → your databaseHow a question travels →You've arrived.
That's the whole route. If something on the way didn't work, the fixes below cover most problems.
Claude Desktop doesn't show NexQL
Quit the app completely and open it again. In Claude Desktop, check Settings → Extensions shows NexQL switched on.Then check the database itself with npx -y nexql-mcp@latest --profile mydb doctor.
"Connection refused" or it times out
Your computer can't reach the database. Check the host and port, and that a firewall, security group or allow list lets your IP in. Cloud databases usually also need sslmode=require.
"password authentication failed"
The user or password is wrong. Run the setup again and retype the password on the setup page or in the dialog.
"permission denied for table …"
The user can't read that table. On Postgres 14 or newer, GRANT pg_read_all_data TO app_reader; lets it read everything.
It says changes are switched off
You're connected as a database superuser, so NexQL stays read-only. To allow changes, connect as a user that isn't a superuser and has the write privileges it needs.