How to Integrate MCP-PostgreSQL-Ops with Claude Desktop: Complete Configuration Guide

Configure Claude Desktop's mcpServers JSON block to launch MCP-PostgreSQL-Ops via uvx with PostgreSQL connection environment variables, enabling natural-language database monitoring through Claude's Tools UI.

MCP-PostgreSQL-Ops provides read-only operational visibility into PostgreSQL databases through a Model Context Protocol (MCP) server. According to the call518/mcp-postgresql-ops repository, integrating this tool with Claude Desktop requires only a single JSON configuration entry that defines how the AI assistant should spawn and communicate with the monitoring server.

Claude Desktop MCP Server Configuration

The integration relies on Claude Desktop's native support for external tools via the mcpServers configuration object. This approach requires no global installation of the Python package, as the uvx command handles dependency resolution and execution at runtime.

Minimal Tool Definition JSON

Create or edit your Claude Desktop configuration file to include the following mcpServers entry:

{
  "mcpServers": {
    "mcp-postgresql-ops": {
      "command": "uvx",
      "args": ["--python", "3.12", "mcp-postgresql-ops"],
      "env": {
        "POSTGRES_HOST": "127.0.0.1",
        "POSTGRES_PORT": "15432",
        "POSTGRES_USER": "postgres",
        "POSTGRES_PASSWORD": "changeme!@34",
        "POSTGRES_DB": "ecommerce"
      }
    }
  }
}

Save this configuration to your Claude Desktop settings file and restart the application. The official integration instructions are documented in the repository's README.md at lines 242-306.

Environment Variable Requirements

The "env" object in the JSON configuration injects PostgreSQL connection credentials directly into the spawned process. The MCP-PostgreSQL-Ops server requires these specific variables:

• POSTGRES_HOST: Database server hostname or IP address
• POSTGRES_PORT: PostgreSQL port number
• POSTGRES_USER: Authentication username
• POSTGRES_PASSWORD: Authentication password
• POSTGRES_DB: Target database name

These variables map to the server implementation in src/mcp_postgresql_ops/mcp_main.py, where the @mcp.tool() decorated functions establish database connections using these credentials.

Alternative Local Server Deployment

For debugging or persistent local development, you can manually launch the MCP server and point Claude Desktop to the HTTP endpoint:

uv run mcp-postgresql-ops \
  --type streamable-http \
  --host 127.0.0.1 \
  --port 8000 \
  --log-level DEBUG

When running in this mode, Claude Desktop can connect to http://127.0.0.1:8000/postgresql-ops by specifying a "url" field instead of the "command" array in the mcpServers configuration. This method is useful when troubleshooting connection issues or developing custom tool extensions referenced in src/mcp_postgresql_ops/prompt_template.md.

Architecture and Source Code References

Understanding the underlying implementation helps troubleshoot integration issues. The MCP-PostgreSQL-Ops integration with Claude Desktop follows this component architecture:

Component	Source Location	Role in Integration
MCP Server Entry Point	src/mcp_postgresql_ops/mcp_main.py	Defines all monitoring tools via @mcp.tool() decorators that Claude invokes through JSON-RPC
Prompt Templates	src/mcp_postgresql_ops/prompt_template.md	Provides natural-language patterns that Claude uses to map user queries to specific database monitoring functions
Configuration Example	README.md (lines 242-306)	Contains the canonical Claude Desktop JSON snippet and setup instructions
Environment Template	.env.example	Documents all supported POSTGRES_* environment variables for connection configuration
Debug Launcher	scripts/run-mcp-inspector-local.sh	Convenience script for local server testing without Claude Desktop

The server implements a read-only, natural-language-driven monitoring API. When Claude Desktop processes a query like "Show all active connections in a clear and readable HTML table," it consults the tool definitions in mcp_main.py and the prompt templates to invoke the appropriate PostgreSQL monitoring functions.

Summary

• Zero-installation integration: Claude Desktop launches MCP-PostgreSQL-Ops on-demand using uvx without requiring global Python package installation
• Credential injection: PostgreSQL connection details pass securely through the "env" field in the mcpServers JSON configuration
• Natural language interface: Once configured, Claude can execute read-only monitoring queries against your PostgreSQL instance using conversational prompts
• Source verification: All tool implementations reside in src/mcp_postgresql_ops/mcp_main.py, with configuration documented in README.md lines 242-306

Frequently Asked Questions

Where do I find the Claude Desktop configuration file location?

Claude Desktop stores the mcpServers configuration in a JSON file whose location varies by operating system. On macOS, this is typically ~/Library/Application Support/Claude/claude_desktop_config.json. Refer to the official Claude documentation for Windows and Linux paths, then paste the MCP-PostgreSQL-Ops server definition into the "mcpServers" object.

Can I use MCP-PostgreSQL-Ops with AI assistants other than Claude Desktop?

Yes. Any AI assistant that supports the Model Context Protocol (MCP) or external tool definitions can integrate with MCP-PostgreSQL-Ops. The server exposes standard JSON-RPC endpoints, so compatible assistants include those that can spawn subprocesses or connect to HTTP streams using the same uvx launch pattern or direct HTTP connections to port 8000.

Is MCP-PostgreSQL-Ops safe to use with production PostgreSQL databases?

The server is designed as a read-only monitoring tool according to the source code in src/mcp_postgresql_ops/mcp_main.py. All implemented tools query system views and statistics tables without executing DDL or DML operations. However, always verify connection credentials use read-only roles with restricted privileges, and review the specific queries in the tool definitions before production deployment.

How do I troubleshoot connection failures between Claude Desktop and the MCP server?

Start the server manually using the uv run command shown in the Alternative Local Server Deployment section with --log-level DEBUG enabled. This exposes detailed connection logs. Additionally, check that all required POSTGRES_* environment variables are correctly defined in the Claude Desktop configuration JSON, and verify the PostgreSQL instance accepts connections from the host where Claude Desktop runs.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}