How to connect Claude Desktop to local databases using Model Context Protocol

How to connect Claude Desktop to local databases using Model Context Protocol

Model Context Protocol (MCP) lets Claude Desktop launch a small local server process that exposes a SQLite or PostgreSQL database as a set of callable tools. Instead of pasting schema dumps into chat and hoping Claude remembers the column names, Claude reads the live schema, drafts SQL against it, runs the query itself, and sees the real result or the real error. Setup takes about ten minutes. Keeping it stable takes more discipline than that.

What actually changes once Claude can see your schema

The old workflow was manual and lossy. You'd run .schema in sqlite3 or pg_dump --schema-only, paste the output into chat, ask for a query, copy that query into a terminal, run it, and paste the result back for interpretation. Every step was copy-paste, and Claude had no way to know its SQL was even valid against your actual tables until a human ran it.

With an MCP database server wired up, Claude gets tool access directly: list tables, inspect column types and constraints, run a SELECT, read the actual rows back, and retry if the first attempt errors out. The schema is never stale because Claude is reading it live during the conversation, not working from something you typed in twenty minutes earlier.

Anthropic describes MCP as the mechanism that lets "AI applications like Claude connect to data sources such as local files and databases, tools such as search engines and calculators, and workflows," a framing laid out in Anthropic's Model Context Protocol documentation. A local database is precisely the use case this was built around, and the reference server implementations for SQLite and PostgreSQL live in the official MCP servers repository on GitHub.

Where does claude_desktop_config.json live, and what goes in it?

Claude Desktop reads MCP server definitions from a single JSON file at startup. On macOS that's ~/Library/Application Support/Claude/claude_desktop_config.json. On Windows it's %APPDATA%\Claude\claude_desktop_config.json. If the file doesn't exist, create it.

Before editing anything, confirm two prerequisites outside of Claude entirely, because debugging MCP and debugging database connectivity at the same time is miserable:

• Node.js is installed if you're running a Node-based server (most reference servers, including the SQLite and Postgres ones, ship as npm packages run through npx). Verify with node --version.
• Your database already connects from a plain terminal. If psql can't reach the instance with the credentials you're about to hand Claude, the MCP server won't succeed either. Fix connectivity first.

Configuring the SQLite server

A minimal SQLite entry looks like this:

1{
2 "mcpServers": {
3 "sqlite": {
4 "command": "npx",
5 "args": [
6 "-y",
7 "@modelcontextprotocol/server-sqlite",
8 "/Users/yourname/projects/app/data.db"
9 ]
10 }
11 }
12}

Three things trip people up here. First, the database path must be absolute. Relative paths resolve against whatever working directory Claude Desktop happens to launch the server from, which is not predictable, and this is the single most common cause of a server that starts cleanly but can't find the file. Second, npx -y fetches the package from npm on first run if it isn't cached, so your first query after editing the config may feel slow for a few seconds while it resolves. Third, you have to fully quit and relaunch Claude Desktop, not just close the window, because the server list is read once at process startup.

Configuring the PostgreSQL server

PostgreSQL brings a connection string into the picture, and this is where environment handling starts to matter:

1{
2 "mcpServers": {
3 "postgres": {
4 "command": "npx",
5 "args": [
6 "-y",
7 "@modelcontextprotocol/server-postgres",
8 "postgresql://appuser:localpassword@localhost:5432/appdb"
9 ]
10 }
11 }
12}

Putting a real password inline in a plain JSON file is a legitimate problem, especially on a shared machine or if that config ever ends up in a dotfiles repo by mistake. The defensible move is pointing the server at a read-only role rather than your main application user:

1CREATE ROLE claude_readonly WITH LOGIN PASSWORD 'use-a-real-secret-here';
2GRANT CONNECT ON DATABASE appdb TO claude_readonly;
3GRANT USAGE ON SCHEMA public TO claude_readonly;
4GRANT SELECT ON ALL TABLES IN SCHEMA public TO claude_readonly;

Do this before wiring up MCP, not after. Claude will write an UPDATE or DELETE statement if you ask it to, directly or by implication, and the Postgres MCP server will execute it without much resistance. A read-only role turns "Claude accidentally wiped a table" into "Claude got a permission denied error," which is a much better failure mode to have while you're still experimenting with prompts.

Does seeing the live schema actually produce better SQL?

Yes, noticeably, and the difference shows up most in queries you wouldn't want to hand-write from memory. Say you have a Postgres database for an e-commerce app with orders, order_items, products, and customers tables, and you want a cohort-style query: customers who placed more than 3 orders in their first 60 days, then went quiet for the following 90.

Ask Claude to "look at the schema for orders, order_items, and customers, then write a query for that cohort." With the MCP server connected, it doesn't ask you to describe the tables. It calls the schema inspection tool, sees the real column names (something is always named created_at in one table and order_date in another), and drafts a query with CTEs and window functions against the actual structure. It executes that query through the same connection, discovers customers.signup_date doesn't exist and the real column is created_on, reads its own error, rewrites the CTE, and runs it again.

That loop, write, execute, read the real error, fix, re-run, is the part that genuinely replaces copy-pasting between a terminal and a chat window. The catch: each of those attempts runs against your real data, so a sloppy first draft with an unindexed join across a few million rows can take a long time to return, and Claude has no sense of your query planner's pain tolerance. It will iterate as many times as it needs to get a clean result, and every slow iteration costs you real wall-clock time sitting there watching a spinner.

Where this gets brittle compared to an IDE's database panel

This setup earns its keep, but it is not a polished product the way a native database integration in an IDE is. The specific failure modes matter more than the general warning:

Process lifecycle problems. The MCP server is a child process Claude Desktop spawns and manages. If it crashes, say from a malformed connection string or a database that went down mid-session, Claude Desktop doesn't always surface a clear error. Sometimes you just get a generic "tool unavailable" message and have to dig through server logs or relaunch the app to understand what happened.

Environment variable scoping. If your Postgres credentials live in .zshrc or .bashrc rather than directly in the config, Claude Desktop may not inherit that shell environment, because it isn't always launched from a session that sources those files. This bites people constantly: the connection works fine from Terminal and fails silently from Claude Desktop. Put credentials directly in the args array or an env block in the server definition instead of relying on ambient shell state.

Version drift. npx -y pulls whatever is tagged latest unless you pin a version. That's convenient until a server package ships a breaking change and your working config stops functioning after a routine cache refresh. Pin a specific version (@modelcontextprotocol/server-postgres@x.y.z) for anything you rely on daily, and check the package listing in the MCP servers repository before upgrading.

No query plan visibility, no autocomplete, no pooling. A real database client gives you EXPLAIN visualization, schema diffing, connection pooling, and query history built into the UI. MCP gives you none of that. You're trading a mature, purpose-built tool for a chat interface that happens to be very good at writing SQL on the fly, and for routine exploration that trade is worth it. For anything touching a system you can't afford to have fumble a connection mid-task, it isn't.

Reach for MCP, or reach for your normal client

The decision isn't really about which tool is "better." It's about what you're doing in a given session.

Use the MCP setup when you're doing ad hoc analysis against a local SQLite export or a dev Postgres instance, and your questions aren't fully formed yet. "What share of users who signed up in Q3 never completed onboarding" is exactly the kind of question where schema exploration and query iteration happening in one continuous conversation beats six manual round trips.

Skip it, and open your actual database client, when you need guaranteed execution safety on something other than a read-only role, when the table is large enough that an exploratory bad join could degrade a shared instance, or when you need EXPLAIN output and index tuning more than you need natural-language query drafting. It's also the wrong call for handing off to non-technical teammates. Installing Node, editing a JSON config by hand, and debugging a server that won't start is still engineering work, not something a product manager can self-serve on the first try.

If you're setting this up for the first time, the technical details of the protocol itself, including how servers register tools and how Claude Desktop discovers them, are documented in the MCP specification, which is worth skimming once before you hit your first brittle failure and need to know whether it's a config problem or a protocol problem.