Claude Desktop MCP Setup for PostgreSQL (2026)

The short answer

Claude can connect to PostgreSQL through MCP in three different ways:

1. Claude Code connects to a local MCP command or a remote HTTP MCP server from the CLI.
2. Claude and Claude Desktop connect to hosted MCP servers through Customize → Connectors.
3. Claude Desktop extensions run local MCP servers when the database or tool must remain on the developer machine.

For a hosted PostgreSQL connection, Claude receives a remote MCP endpoint and authenticates to it. The MCP server stores or receives the database credential, exposes schema and query tools, enforces its policy, and executes SQL through a PostgreSQL role.

You no longer need mcp-remote to connect Claude Desktop to a supported remote MCP server. Anthropic's current documentation lists remote custom connectors as a beta feature on Free, Pro, Max, Team, and Enterprise plans; Free users are limited to one custom connector.

For general CLI installation, .mcp.json, local/project/user scopes, and non-database examples, use the dedicated Claude Code MCP setup guide. For the complete database-specific CLI workflow, use the Claude Code PostgreSQL MCP guide. This page owns PostgreSQL setup for Claude Desktop and Claude on the web through Connectors.

Claude PostgreSQL MCP options compared

Local, provider-specific, and hosted servers solve different problems. Compare current implementations in Best PostgreSQL MCP Servers before copying an old package name from a setup article.

For the hosted product path, review the PostgreSQL MCP server for controlled database access, then return here for the Claude-specific steps.

Ready to test it in Claude? Create one free PostgreSQL MCP link, keep the first link read-only, and use the verification steps below before granting write access.

Requirements

For the hosted datamcp path, you need:

• PostgreSQL 12 or newer
• a dedicated PostgreSQL role with the required grants
• a datamcp account and MCP link
• Claude Code, or a Claude plan that supports remote custom connectors
• a remote MCP URL reachable over HTTPS

Anthropic currently lists Free, Pro, Max, Team, and Enterprise for remote custom connectors. Free users are limited to one custom connector. Team and Enterprise owners configure organization connectors; users then connect and enable the connector individually.

Option 1: Connect Claude Code to datamcp PostgreSQL

Claude Code supports remote HTTP MCP servers directly.

Step 1: Create a PostgreSQL connection

In datamcp, add the PostgreSQL host, port, database, role, password, and applicable TLS settings. Use a dedicated role instead of an owner or migration account.

datamcp encrypts PostgreSQL credentials at rest with AES-256-GCM and keeps them outside the Claude configuration.

Step 2: Create an MCP link

Choose the narrowest link policy that supports the task:

• Read Only permits SELECT
• Read, Write & Delete permits SELECT, INSERT, UPDATE, and DELETE, but not DDL
• Full Access permits operations allowed by the effective database role
• Custom limits table-level operations and remains bounded by the database role

Start with Read Only and test a denied write before adding broader access.

Step 3: Add the remote server

Use the remote URL and API key shown for the MCP link:

claude mcp add --transport http app-database \
  "https://api.datamcp.app/api/mcp/YOUR_CONNECTION_ID" \
  --header "Authorization: Bearer YOUR_DATAMCP_API_KEY"

Then open Claude Code and run:

/mcp

Confirm that app-database is connected and inspect the available tools.

Step 4: Test the permission boundary

Begin with schema inspection:

Use app-database to list the schemas and show my effective permissions. Do not run a data query yet.

Then run one narrow query:

Count completed orders by month for the last six months. Explain the tables and columns before executing SQL.

Finally, if the link is read-only, request an UPDATE and confirm that execution is denied.

Option 2: Connect Claude or Claude Desktop through Connectors

Anthropic's current hosted flow uses remote custom connectors. Do not place a remote server only in claude_desktop_config.json; Anthropic documents adding remote servers through Customize → Connectors.

Free, Pro, and Max

1. Open Customize → Connectors.
2. Find the Connectors section.
3. Choose Add custom connector.
4. Enter a recognizable name.
5. Paste the datamcp remote MCP URL intended for Claude OAuth.
6. Add the connector and complete authentication.

Team and Enterprise

An owner or primary owner first adds the remote server under organization connectors. Individual users then connect their account and enable the connector in conversations.

Use the Search and tools menu to enable the database connector and disable tools that the current conversation does not need.

Authentication

datamcp supports OAuth 2.0 with PKCE for compatible clients. Claude authenticates to the MCP endpoint; the PostgreSQL credential remains on the datamcp connection side.

These are separate boundaries:

• Claude identity and connector access
• datamcp MCP link policy
• PostgreSQL role grants

Read MCP authorization, permissions, and scopes for the complete model.

Option 3: Run a local PostgreSQL MCP server

A local server remains useful for a development database controlled by one developer. Claude Desktop can run local MCP through desktop extensions, and Claude Code can start local commands.

Do not begin a new setup with the deprecated, archived @modelcontextprotocol/server-postgres reference package merely because older guides still show it. If it is already installed, follow the PostgreSQL MCP migration guide and preserve the read-only database boundary.

Current alternatives include Postgres MCP Pro by CrystalDBA, which focuses on PostgreSQL performance analysis, health checks, query plans, and index tuning.

A typical Claude Code local command follows this pattern:

claude mcp add local-postgres -- \
  npx -y @crystaldba/postgres-mcp \
  "postgresql://user:password@localhost:5432/database"

Verify the current package documentation before installation. A local configuration places the database credential or its environment variable on the machine and makes that machine responsible for package updates and process security.

Choose local when: the database is local or disposable, one trusted user controls the machine, and centralized revocation is unnecessary.

Choose hosted when: several clients or people need separate access, the database credential should not be distributed, or activity needs one review surface.

What Claude can do with datamcp PostgreSQL tools

datamcp currently exposes six PostgreSQL MCP tools:

• query
• get_permissions
• get_schema
• get_table_details
• get_schema_changes
• resync_schema

Useful workflows include:

Understand an unfamiliar schema

Inspect the schema and explain how customers, subscriptions, invoices, and payments relate. Do not return customer rows.

Build and run analytics SQL

Calculate monthly recurring revenue by plan for the last year. Show the proposed SQL before executing it.

Investigate a failed query

Inspect the referenced tables and indexes, explain why this query may fail or perform poorly, and propose a corrected query. Do not create indexes.

datamcp is not a replacement for a specialized PostgreSQL tuning server. It does not currently provide CrystalDBA-style hypothetical index analysis or automated performance tuning.

Claude Code vs Claude Desktop for PostgreSQL MCP

Choose Claude Code when the database context is part of coding, migrations, debugging, or repository work. Its CLI makes local and remote MCP configuration explicit and easy to scope to a project.

Choose Claude or Claude Desktop Connectors when the database is used for analysis, operations, or cross-source conversations outside a code repository.

Choose a local desktop extension when the source must be reached through a local process and sending requests to a hosted MCP provider is not acceptable.

The remote datamcp endpoint can also be used with separately governed links for Cursor, ChatGPT, and supported VS Code MCP workflows.

Troubleshooting

Claude Code reports a disconnected server

• Run /mcp and inspect the server status.
• Confirm the remote URL is correct and reachable over HTTPS.
• Confirm the API key and MCP link are active.
• Verify that the authorization header starts with Bearer .
• Remove and re-add the server after changing transport or authentication.

Claude or Claude Desktop cannot add the connector

• Confirm the account has an available custom connector slot; Free accounts currently have one.
• Add remote servers through Customize → Connectors, not only through claude_desktop_config.json.
• For Team or Enterprise, confirm an owner enabled the organization connector.
• Check whether the beta feature is available in the current client version.

OAuth succeeds but tools are unavailable

• Enable the connector through Search and tools in the conversation.
• Confirm the authorizing datamcp user can access the connection and MCP link.
• Reconnect if the wrong database link was authorized.
• Disable unrelated tools to reduce selection ambiguity.

Schema works but a query is denied

• Inspect get_permissions.
• Review the MCP link preset or custom table operations.
• Check the PostgreSQL role grants.
• Review the denied operation in datamcp activity logs.

Security checklist

1. Connect only to a remote MCP server you trust.
2. Use a dedicated PostgreSQL role.
3. Start with Read Only.
4. Keep production separate from development.
5. Enable only the tools needed for the conversation.
6. Review Claude's tool approvals before write actions.
7. Test a denied operation.
8. Revoke the link when the client or user no longer needs access.

Anthropic warns that remote custom connectors may expose Claude to unverified tools and prompt injection. Review requested permissions and avoid “Allow always” for write-capable database tools unless the server, policy, and workflow have been vetted.

Get started

Create one PostgreSQL connection and one MCP link for free. Begin with a dedicated read-only role, connect Claude Code or a supported Claude connector, and verify schema access plus a denied write before expanding permissions.

For the product overview, visit Claude PostgreSQL MCP. For deployment tradeoffs, read Hosted vs Local MCP Servers.