Skip to main content
Glama
martymarkenson

PostgreSQL MCP Server

by martymarkenson
OverviewSchemaRelated ServersScoreDiscussions
TypeScript
Hybrid

PostgreSQL MCP Server

An MCP (Model Context Protocol) server for querying a PostgreSQL database. Execute SQL queries, view table details, and manage database connections through MCP-compatible clients.

Key Features

  • Database Connection: Connect to PostgreSQL databases with authentication

  • SQL Execution: Execute SELECT queries with security validation

  • Connection Testing: Test database connection status

Related MCP server: PostgreSQL MCP Server

Installation

Claude Desktop

Follow these steps for installation:

Step 1: Download the MCP Server

Download the postgres-connector.mcpb file from this repository (located in the root directory).

Step 2: Install the MCP Server

  1. Open Claude Desktop

  2. Navigate to Settings > Features

  3. Click "Install Extension" and select the postgres-connector.mcpb file

Installation Step 2 Screenshot placeholder: Installing the .mcpb file

Step 3: Configure Database Connection

After installation, the PostgreSQL Connector will appear in your Claude Desktop with default environment variables that you can configure with your database details.

Configuration Screen Screenshot placeholder: Database configuration interface showing environment variables

Step 4: Test the database connection

Send a query "test the database connection" Test Database Connection

Configuration

Required Database Settings

You'll need to provide the following information for your PostgreSQL database:

Environment Variable

Description

Required

Default

POSTGRES_HOST

The hostname or IP address of your PostgreSQL server

✅ Yes

-

POSTGRES_PORT

The port number for your PostgreSQL server

❌ No

5432

POSTGRES_DB

The name of the specific database to connect to

✅ Yes

-

POSTGRES_USER

Your PostgreSQL username

✅ Yes

-

POSTGRES_PASSWORD

Your PostgreSQL password

✅ Yes

-

These environment variables will be automatically available for configuration in the extension settings panel after installing the extension in Claude Desktop.

Available Tools

1. Test PostgreSQL Connection

Tool: test-postgres-connection

Tests your database connection and displays the current configuration (password hidden for security).

Example Output:

✅ Database connection successful!

Configuration:
{
  "host": "localhost",
  "port": "5432",
  "database": "myapp_production",
  "username": "postgres",
  "password": "***hidden***"
}

Connection test result: [
  {
    "test": 1
  }
]

2. Get All Tables

Tool: get-all-tables

Retrieves a list of all tables in the public schema of your database.

Example Output:

[
  {
    "table_name": "users"
  },
  {
    "table_name": "orders"
  },
  {
    "table_name": "products"
  },
  {
    "table_name": "categories"
  }
]

3. Execute SQL Query

Tool: execute-sql-query

Executes SELECT queries on your database with security validation.

Input:

  • sql: The SQL query to execute (SELECT statements only)

Example Usage:

SELECT id, name, email FROM users LIMIT 5;

Example Output:

[
  {
    "id": 1,
    "name": "John Doe",
    "email": "john@example.com"
  },
  {
    "id": 2,
    "name": "Jane Smith",
    "email": "jane@example.com"
  }
]

Security & Safety

SQL Query Validation

The PostgreSQL MCP server includes security measures:

  • READ-ONLY Operations: Only SELECT statements are permitted

  • Dangerous Keywords Blocked: DROP, DELETE, TRUNCATE, ALTER, CREATE, INSERT, UPDATE operations are automatically blocked

  • Statement-Level Validation: Each SQL statement is validated individually

  • Safe Error Handling: Database errors are caught and displayed safely

Best practice is to create a read-only database user for the postgres connector to use.

Blocked Operations

The following SQL operations are NOT ALLOWED for security:

  • DROP (deleting tables/databases)

  • DELETE (removing data)

  • TRUNCATE (clearing tables)

  • ALTER (modifying structure)

  • CREATE (creating new objects)

  • INSERT (adding data)

  • UPDATE (modifying data)

Usage Examples

Get Database Tables

Use the get-all-tables tool to retrieve all tables in your database schema.

Execute Queries

Use the execute-sql-query tool with SELECT statements:

SELECT * FROM users LIMIT 10;

Troubleshooting

Connection Issues

Problem: "Database connection failed"

  • Check: Verify your host, port, database name, username, and password

  • Check: Ensure your PostgreSQL server is running and accessible

  • Check: Verify that your database user has the necessary permissions

Problem: "Connection timeout"

  • Check: Your database server might be behind a firewall

  • Check: The host address and port number are correct

  • Check: Network connectivity to the database server

Query Issues

Problem: "Dangerous operation detected"

  • Cause: You're trying to execute a non-SELECT statement

  • Solution: Only SELECT queries are allowed for security reasons

Problem: "Query execution failed"

  • Check: Your SQL syntax is correct

  • Check: The tables and columns you're referencing exist

  • Check: Your database user has SELECT permissions on the tables

Configuration Issues

Problem: MCP server not appearing in Claude Desktop client

  • Solution: Restart Claude Desktop

  • Check: Verify the .mcpb file was installed correctly

  • Check: Look for any error messages in Claude Desktop's console

Problem: Environment variables not showing up

  • Solution: Restart Claude Desktop after installation

  • Check: Ensure the extension is enabled in Settings > Features

Problem: Cannot configure database settings

  • Solution: Make sure all required environment variables are filled out

  • Check: Verify your database credentials are correct

Technical Details

System Requirements

  • PostgreSQL database (version 9.0 or higher)

  • Network access to your PostgreSQL server

Dependencies

  • Node.js runtime

  • PostgreSQL client libraries

  • MCP (Model Context Protocol) framework

Project Structure

postgres-connector/
├── src/
│   └── server.ts          # Main MCP server implementation
├── package.json           # Node.js dependencies
├── manifest.json          # MCP extension manifest
├── icon.png              # Extension icon
└── postgres-connector.mcpb # Compiled extension bundle

License

MIT License - see the LICENSE file for details.

Author

Marty Markenson

Need help? Open an issue in this repository or reach out to martymarkenson

Available Tools

3 tools
execute-sql-queryExecute SQL QueryA

Execute a SQL query on the database. Only SELECT statements are allowed for security.

ParametersJSON Schema
NameRequiredDescriptionDefault
sqlYesThe SQL query to execute

TDQS

A4/5.0
Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations provided, so description carries full burden. It discloses the SELECT-only constraint but omits behaviors like result format, error handling, or execution limits. This is minimal for a read-only query tool.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single, efficient sentence with no unnecessary words. It front-loads the purpose and constraint.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a tool with one parameter and no output schema, the description covers purpose and constraint well. However, it lacks details on output format or error behavior, which would enhance completeness for an agent.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, and the description adds no extra meaning to the 'sql' parameter beyond what the schema provides. Baseline 3 is appropriate as the schema already documents it adequately.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the verb 'execute', the resource 'SQL query on the database', and a critical constraint 'Only SELECT statements are allowed'. This distinguishes it from siblings like get-all-tables and test-postgres-connection.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description provides a clear usage constraint ('Only SELECT statements') and a reason (security). It implicitly tells when to use (read queries) but doesn't explicitly state when not to or suggest alternatives, though siblings are limited.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

get-all-tablesGet All Tables QueryA

Execute SQL queries to get all tables in the database

ParametersJSON Schema
NameRequiredDescriptionDefault

No parameters

TDQS

A3.7/5.0
Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations exist, so the description must disclose behavioral traits. It does not explicitly state the tool is read-only or mention any side effects, and the phrasing 'Execute SQL queries' could mislead about parameters.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single sentence with no wasted words, front-loading the core action.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness3/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

The description is adequate for a simple, parameterless tool, but it does not describe the return value format, which is missing since there is no output schema.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The input schema has no parameters (100% coverage), so baseline is 3. The description does not add parameter meaning beyond the schema, but it clarifies the tool's purpose.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool gets all tables in the database, with a specific verb and resource. It is distinct from siblings 'execute-sql-query' and 'test-postgres-connection'.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description provides clear context that the tool lists all tables, but does not explicitly mention when to avoid using it or compare it to alternatives.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

test-postgres-connectionTest Postgres ConnectionA

Test the Postgres connection and return connection status

ParametersJSON Schema
NameRequiredDescriptionDefault

No parameters

TDQS

A4/5.0
Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

The description discloses the basic behavior: testing connection and returning status. No annotations are provided, so the description carries the full burden. It lacks details on whether the test modifies state, requires authentication, or has side effects, but for a test tool the behavior is straightforward.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single sentence with no filler or redundant information. It is front-loaded and efficient.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

The tool is simple (no parameters, no output schema), and the description adequately communicates its purpose and result. It could elaborate on what 'connection status' entails (e.g., boolean, string), but the essential information is present.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The input schema has no parameters (0 params), so schema description coverage is 100%. The description does not need to add parameter details, and baseline for 0 params is 4.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the action (test) and resource (Postgres connection) and indicates the output (connection status). It effectively distinguishes from siblings: execute-sql-query runs queries and get-all-tables retrieves schemas.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description does not provide explicit guidance on when to use this tool versus alternatives. However, the purpose is self-explanatory as a diagnostic check, so usage is implied but not explicitly stated.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections. Dates show when Glama detected each change.

  1. 1 tool updatev1.0.0
    • Changedexecute-sql-query2 fields changed
      • addedInput schema / $schema
        Added value: +"http://json-schema.org/draft-07/schema#"
      • addedInput schema / additionalProperties
        Added value: +false
  2. 3 tool updates
    • First observedexecute-sql-query
    • First observedget-all-tables
    • First observedtest-postgres-connection
Install Server
RayrunBuild, deploy, and operate MCP servers without becoming an infrastructure team.ray.runAd

TDQS

A3.6/5.0
Disambiguation5/5

Each tool has a clearly distinct purpose: executing SELECT queries, listing all tables, and testing connection. There is no overlap.

Naming Consistency5/5

All tool names follow a consistent verb_noun pattern with snake_case: execute-sql-query, get-all-tables, test-postgres-connection.

Tool Count2/5

Only 3 tools for a PostgreSQL server is extremely limited. Typical servers require many more operations (CRUD, schema management, etc.), making this count too low for the domain.

Completeness1/5

The server only supports SELECT queries, listing tables, and connection testing. Missing essential operations like INSERT, UPDATE, DELETE, schema inspection, and index management, severely limiting usefulness.

Maintenance

ActivityInactive
ResponsivenessNo issues

Resources

Unclaimed servers have limited discoverability.

Looking for Admin?

If you are the server author, to access and configure the admin panel.

Related MCP Connectors

Related MCP Servers

  • Postgres MCP Server

    eddykuhan
    F
    license
    Not graded
    quality
    D
    maintenance
    Enables interaction with PostgreSQL databases through MCP, allowing users to explore database structures, inspect table schemas, and execute read-only SQL queries.
    -

  • PostgreSQL MCP Server

    codescept
    -
    license
    Not graded
    quality
    Not graded
    maintenance
    Enables users to perform SQL query execution, schema exploration, and performance analysis on PostgreSQL databases through any MCP-compatible client. It prioritizes security with read-only protection by default and provides guided workflows for database documentation and optimization.
    -

  • dbmcp

    iSunRise
    F
    license
    Not graded
    quality
    B
    maintenance
    Enables querying PostgreSQL databases via MCP, with multi-database routing, credential isolation, and truncated results plus full CSV export.
    -

  • mcp-postgres

    gbfeliped
    A
    license
    Not graded
    quality
    C
    maintenance
    Read-only PostgreSQL MCP server that enables running SELECT queries, listing tables and schemas, and describing columns, with built-in protection against writes and malicious SQL attacks.
    751
    MIT

Appeared in Searches

Latest Blog Posts

MCP directory API

We provide all the information about MCP servers via our MCP API.

curl -X GET 'https://glama.ai/api/mcp/v1/servers/martymarkenson/Postgres-Connector-MCP'

If you have feedback or need assistance with the MCP directory API, please join our Discord server