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

> Integrate MCP-PostgreSQL-Ops with Claude Desktop using the mcpServers JSON block and uvx for natural-language database monitoring. Get the complete configuration guide.

- Repository: [JungJungIn/mcp-postgresql-ops](https://github.com/call518/mcp-postgresql-ops)
- Tags: how-to-guide
- Published: 2026-02-26

---

**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:

```json
{
  "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`](https://github.com/call518/mcp-postgresql-ops/blob/main/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`](https://github.com/call518/mcp-postgresql-ops/blob/main/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:

```bash
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`](https://github.com/call518/mcp-postgresql-ops/blob/main/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`](https://github.com/call518/mcp-postgresql-ops/blob/main/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`](https://github.com/call518/mcp-postgresql-ops/blob/main/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`](https://github.com/call518/mcp-postgresql-ops/blob/main/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`](https://github.com/call518/mcp-postgresql-ops/blob/main/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`](https://github.com/call518/mcp-postgresql-ops/blob/main/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`](https://github.com/call518/mcp-postgresql-ops/blob/main/src/mcp_postgresql_ops/mcp_main.py), with configuration documented in [`README.md`](https://github.com/call518/mcp-postgresql-ops/blob/main/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`](https://github.com/call518/mcp-postgresql-ops/blob/main/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.