Skip to main content
Glama
cesarvarela

PostgreSQL MCP Server

by cesarvarela
OverviewSchemaRelated ServersScoreDiscussions
TypeScript

PostgreSQL MCP Server

A TypeScript-based Model Context Protocol (MCP) server that provides AI assistants with secure, structured access to PostgreSQL databases.

Features

  • Safe Database Operations: All queries use parameterized statements to prevent SQL injection

  • Comprehensive Tools: Query, insert, update, delete data with full schema introspection

  • Flexible Querying: Support for filtering, pagination, sorting, and complex WHERE conditions

  • Schema Discovery: Get detailed information about tables, columns, constraints, and indexes

  • Connection Pooling: Efficient database connection management

  • Error Handling: Comprehensive error reporting without exposing sensitive information

  • Safety Checks: Required WHERE clauses for updates/deletes, confirmation for large operations

Related MCP server: SQL MCP Server

Tools Available

query-table

Query data from a specific table with filtering, pagination, and sorting.

Parameters:

  • table (string, required): Table name to query

  • columns (string[], optional): Specific columns to select (default: all)

  • where (object, optional): WHERE conditions (supports equality, arrays for IN, wildcards for LIKE)

  • pagination (object, optional): {limit: number, offset: number}

  • sort (object, optional): {column: string, direction: "ASC"|"DESC"}

get-schema

Get database schema information including tables, columns, and constraints.

Parameters:

  • schema_name (string, optional): Schema to inspect (default: "public")

  • table_pattern (string, optional): LIKE pattern for table names

  • include_columns (boolean, optional): Include column details (default: true)

  • include_constraints (boolean, optional): Include constraint details (default: false)

execute-query

Execute a parameterized SQL query with safety checks.

Parameters:

  • query (string, required): SQL query with parameter placeholders ($1, $2, etc.)

  • params (any[], optional): Parameters for the query

  • explain (boolean, optional): Include execution plan (default: false)

insert-data

Insert new records into a table.

Parameters:

  • table (string, required): Target table name

  • data (object|object[], required): Data to insert (single record or array)

  • on_conflict (string, optional): Conflict resolution: "error", "ignore", "update" (default: "error")

  • conflict_columns (string[], optional): Columns to check for conflicts

  • returning (string[], optional): Columns to return (default: ["*"])

update-data

Update existing records in a table.

Parameters:

  • table (string, required): Target table name

  • data (object, required): Data to update

  • where (object, required): WHERE conditions (required for safety)

  • returning (string[], optional): Columns to return (default: ["*"])

delete-data

Delete records from a table.

Parameters:

  • table (string, required): Target table name

  • where (object, required): WHERE conditions (required for safety)

  • confirm_delete (boolean, optional): Bypass confirmation for large deletes

  • returning (string[], optional): Columns to return from deleted records

get-table-info

Get detailed information about a specific table.

Parameters:

  • table (string, required): Table name

  • schema_name (string, optional): Schema name (default: "public")

  • include_statistics (boolean, optional): Include size and row count stats (default: true)

connection-status

Check database connection status, view error details, and retry connection.

Parameters:

  • retry (boolean, optional): Attempt to reconnect if connection is currently failed (default: false)

Returns:

  • Current connection status ("connected", "failed", or "unknown")

  • Error details if connection failed

  • Last connection attempt timestamp

  • Troubleshooting information for failed connections

  • Result of retry attempt if retry was requested

Installation

npm install

Configuration

Create a .env file based on .env.example:

cp .env.example .env

Set your PostgreSQL connection details:

# Required: PostgreSQL connection string
DATABASE_URL=postgresql://username:password@localhost:5432/database_name

# Optional: Individual connection parameters
# POSTGRES_HOST=localhost
# POSTGRES_PORT=5432
# POSTGRES_DB=database_name
# POSTGRES_USER=username
# POSTGRES_PASSWORD=password

# Optional: Environment and debugging
NODE_ENV=development
DEBUG=postgres-mcp*

# Optional: Connection pool settings
MAX_CONNECTIONS=20
QUERY_TIMEOUT=30000

Usage

Development

# Start in development mode with auto-reload
npm run dev

# Or start normally
npm start

Production

# Build the project
npm run build

# Run the built version
node dist/index.js

As an MCP Server

Add to your MCP client configuration (e.g., Claude Desktop):

{
  "mcpServers": {
    "postgres": {
      "command": "node",
      "args": ["/path/to/postgres-mcp/dist/index.js"],
      "env": {
        "DATABASE_URL": "postgresql://username:password@localhost:5432/database_name"
      }
    }
  }
}

Security Considerations

  1. Parameterized Queries: All SQL operations use parameter binding to prevent injection attacks

  2. Identifier Validation: Table and column names are validated against PostgreSQL naming rules

  3. Required WHERE Clauses: UPDATE and DELETE operations require WHERE conditions for safety

  4. Large Operation Warnings: Confirmation required for operations affecting >100 rows

  5. Connection Security: Use SSL connections in production environments

  6. Access Control: Configure database-level permissions appropriately

Database Permissions

The database user should have appropriate permissions for the operations you want to allow:

-- For read-only access
GRANT SELECT ON ALL TABLES IN SCHEMA public TO your_user;

-- For full access
GRANT SELECT, INSERT, UPDATE, DELETE ON ALL TABLES IN SCHEMA public TO your_user;

-- For schema introspection
GRANT USAGE ON SCHEMA information_schema TO your_user;
GRANT SELECT ON ALL TABLES IN SCHEMA information_schema TO your_user;

Example Usage

Once connected through an MCP client:

AI: Can you show me the structure of the users table?
Assistant: I'll get the table information for you.

[Uses get-table-info tool]

The users table has the following structure:
- id (integer, primary key)
- email (varchar, unique, not null)
- name (varchar)
- created_at (timestamp with time zone)
...
AI: Find all users created in the last 7 days
Assistant: I'll query the users table for recent records.

[Uses query-table tool with WHERE condition]

Found 15 users created in the last 7 days:
...

Development

Testing

This project includes comprehensive tests using Vitest and Testcontainers for real PostgreSQL database testing.

Prerequisites:

  • Docker must be installed and running (for testcontainers)

Run all tests:

npm test

Run tests in watch mode:

# Watch mode for development
npm run test:watch

Type Checking

npm run typecheck

Building

npm run build

Architecture

  • index.ts: Main server entry point and tool registration

  • tools/utils.ts: Shared utilities, database connection, and helper functions

  • tools/*.ts: Individual tool implementations

  • tests/: Comprehensive test suite

  • tsup.config.ts: Build configuration

  • tsconfig.json: TypeScript configuration

  • vitest.config.ts: Test configuration

Error Handling

All tools include comprehensive error handling:

  • Input validation with Zod schemas

  • Database connection error handling

  • SQL execution error handling

  • Graceful error responses to MCP clients

  • Graceful startup: Server starts even if database is unavailable

  • Connection recovery: Ability to retry connections without restarting

Connection Troubleshooting

If the database connection fails at startup or during operation, the server will continue running and provide helpful error information through the connection-status tool.

Common connection issues:

  1. Database server not running: Ensure PostgreSQL is running and accessible

  2. Invalid credentials: Check username, password, and database name in your configuration

  3. Network connectivity: Verify host, port, and firewall settings

  4. SSL/TLS issues: Check SSL configuration for production environments

  5. Connection string format: Ensure DATABASE_URL follows the correct format

To diagnose and fix connection issues:

  1. Check connection status:

    Use the connection-status tool to see current status and error details

  2. Verify configuration:

    # Check your .env file or environment variables
echo $DATABASE_URL
# Should look like: postgresql://username:password@host:port/database

  3. Test manually:

    # Test connection with psql
psql $DATABASE_URL -c "SELECT 1;"

  4. Retry connection:

    Use the connection-status tool with retry: true to attempt reconnection

Graceful degradation:

  • If database connection fails, all database tools will return helpful error messages

  • Error messages include specific troubleshooting steps

  • Tools automatically guide users to use connection-status for diagnosis and retry

  • Once connection is restored (via retry), all tools resume normal operation

Contributing

  1. Follow the existing code patterns

  2. Add proper TypeScript types

  3. Include error handling

  4. Test with a real PostgreSQL database

  5. Update documentation as needed

License

MIT License

Available Tools

8 tools
connection-statusA

Check database connection status, view error details, and retry connection. Use retry: true to attempt reconnection when database is unavailable.

ParametersJSON Schema
NameRequiredDescriptionDefault
retryNo

TDQS

A4.1/5.0
Behavior3/5

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

With no annotations provided, the description carries the full burden. It discloses that the tool can check status, view error details, and retry connections, which covers basic behavior. However, it doesn't mention important aspects like whether this requires special permissions, what format error details come in, or if there are rate limits on retry attempts.

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 perfectly concise with two sentences that each earn their place. The first sentence states the core functionality, and the second provides specific parameter guidance. No wasted words or redundant information.

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?

For a diagnostic tool with no annotations and no output schema, the description provides adequate but minimal information. It covers what the tool does and parameter usage, but doesn't explain what the output looks like (status format, error detail structure) or potential side effects of retrying.

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 schema has 0% description coverage for its single parameter. The description compensates by explaining the 'retry' parameter's purpose ('attempt reconnection when database is unavailable') and when to use it ('Use retry: true'). This adds meaningful context beyond the bare schema.

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's purpose with specific verbs ('check', 'view', 'retry') and resource ('database connection status'). It distinguishes from siblings like execute-query or get-schema by focusing on connection health rather than data operations.

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 for when to use the tool ('when database is unavailable') and mentions the retry parameter usage. However, it doesn't explicitly state when NOT to use it or name specific alternatives among the sibling tools.

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

delete-dataA

Delete records from a table. Requires WHERE conditions for safety. Includes confirmation prompt for large deletions.

ParametersJSON Schema
NameRequiredDescriptionDefault
tableYes
whereYes
confirm_deleteNo
returningNo

TDQS

A3.7/5.0
Behavior4/5

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

With no annotations provided, the description carries the full burden and does well by disclosing key behavioral traits: it's a destructive operation (implied by 'Delete'), requires safety measures ('WHERE conditions for safety'), and includes interactive elements ('confirmation prompt for large deletions'). It doesn't cover aspects like permissions or rate limits, but provides solid foundational context.

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 highly concise and front-loaded, with two sentences that directly convey purpose and key behaviors without any wasted words. Each sentence earns its place by providing essential information, making it efficient and well-structured.

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?

Given the tool's complexity (destructive operation with 4 parameters, no output schema, and no annotations), the description is minimally adequate. It covers the core action and safety notes but lacks details on parameter usage, return values, or error handling. It meets basic needs but has clear gaps for a tool of this nature.

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 description coverage is 0%, so the description must compensate, but it only partially does so. It mentions 'WHERE conditions' (mapping to the 'where' parameter) and hints at 'confirmation prompt' (related to 'confirm_delete'), but doesn't explain 'table', 'returning', or the structure of 'where'. This adds some meaning but leaves significant gaps, aligning with the baseline for moderate coverage.

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

Purpose4/5

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

The description clearly states the action ('Delete records') and target resource ('from a table'), which is specific and unambiguous. However, it doesn't explicitly differentiate from sibling tools like 'execute-query' or 'update-data' that might also modify data, though the verb 'Delete' is distinct enough for basic differentiation.

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 implies usage by stating 'Requires WHERE conditions for safety' and 'Includes confirmation prompt for large deletions,' which suggests when to use it (for deletion with conditions) and hints at safety considerations. However, it doesn't explicitly compare to alternatives like 'update-data' or specify when not to use it, leaving some ambiguity.

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

execute-queryC

Execute a parameterized SQL query with safety checks. Supports SELECT, INSERT, UPDATE, DELETE operations with parameter binding to prevent SQL injection.

ParametersJSON Schema
NameRequiredDescriptionDefault
queryYes
paramsNo
explainNo

TDQS

C2.9/5.0
Behavior3/5

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

With no annotations provided, the description carries the full burden. It discloses safety checks and parameter binding to prevent SQL injection, which are useful behavioral traits. However, it lacks details on permissions, rate limits, error handling, or what 'safety checks' entail, leaving gaps for a mutation-capable tool.

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

Conciseness4/5

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

The description is appropriately concise with two sentences that are front-loaded and avoid redundancy. Each sentence adds value: the first states the core functionality, and the second expands on supported operations and safety features.

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

Completeness2/5

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

Given the tool's complexity (supports mutations, 3 parameters with 0% schema coverage, no output schema, and no annotations), the description is incomplete. It lacks details on return values, error conditions, transactional behavior, and when to use versus siblings, making it inadequate for safe agent operation.

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

Parameters2/5

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

Schema description coverage is 0%, so the description must compensate but adds minimal parameter semantics. It mentions 'parameterized SQL query' and 'parameter binding' hinting at 'query' and 'params', but doesn't explain 'explain' or provide syntax/format details. With 3 parameters undocumented, this is insufficient.

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

Purpose4/5

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

The description clearly states the tool's purpose: 'Execute a parameterized SQL query with safety checks' specifies the verb (execute) and resource (SQL query), and mentions support for SELECT, INSERT, UPDATE, DELETE operations. It distinguishes from siblings like 'query-table' by being more general, though not explicitly contrasting them.

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

Usage Guidelines2/5

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

The description provides no guidance on when to use this tool versus alternatives like 'query-table', 'insert-data', 'update-data', or 'delete-data'. It mentions support for various SQL operations but doesn't specify contexts, prerequisites, or exclusions for choosing among siblings.

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

get-schemaB

Get database schema information including tables, columns, data types, and optionally constraints. Useful for understanding database structure.

ParametersJSON Schema
NameRequiredDescriptionDefault
schema_nameNopublic
table_patternNo
include_columnsNo
include_constraintsNo

TDQS

B3/5.0
Behavior2/5

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

No annotations are provided, so the description carries the full burden of behavioral disclosure. It describes what information is retrieved but lacks details on behavioral traits such as whether this is a read-only operation (implied by 'Get' but not stated), potential performance impacts, error conditions, or the format of the returned data. The description is minimal and doesn't compensate for the absence of annotations.

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 concise and well-structured with two sentences: the first states the purpose and key parameters, and the second provides usage context. Every sentence adds value without redundancy, making it efficient and easy to parse.

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

Completeness2/5

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

Given the complexity (4 parameters with 0% schema coverage, no annotations, no output schema), the description is incomplete. It doesn't explain parameter meanings, behavioral aspects like safety or output format, or how it relates to sibling tools. For a tool that retrieves database schema—a potentially complex operation—this leaves significant gaps for an AI agent to understand and use it correctly.

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

Parameters2/5

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

Schema description coverage is 0%, meaning none of the 4 parameters are documented in the schema. The description mentions 'optionally constraints' which hints at the 'include_constraints' parameter, but it doesn't explain the other parameters (schema_name, table_pattern, include_columns) or their purposes. This adds minimal value beyond the schema, failing to compensate for the low coverage.

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

Purpose4/5

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

The description clearly states the tool's purpose: 'Get database schema information including tables, columns, data types, and optionally constraints.' It specifies the verb ('Get') and resource ('database schema information') with concrete examples of what information is retrieved. However, it doesn't explicitly differentiate from sibling tools like 'get-table-info' or 'query-table', which might also provide schema-related information.

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 provides some usage context: 'Useful for understanding database structure.' This implies when to use it (for structural understanding) but doesn't explicitly state when not to use it or mention alternatives among the sibling tools. For example, it doesn't clarify how this differs from 'get-table-info' or when to prefer one over the other.

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

get-table-infoB

Get detailed information about a specific table including columns, constraints, indexes, and optionally statistics like row count and size.

ParametersJSON Schema
NameRequiredDescriptionDefault
tableYes
schema_nameNopublic
include_statisticsNo

TDQS

B3.1/5.0
Behavior2/5

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

No annotations are provided, so the description carries the full burden of behavioral disclosure. It describes what information is returned but doesn't mention critical behavioral aspects like whether this is a read-only operation, potential performance impact, authentication requirements, error conditions, or response format. For a metadata retrieval tool with zero annotation coverage, this leaves significant gaps in understanding how the tool behaves.

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

Conciseness4/5

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

The description is a single, efficient sentence that front-loads the core purpose and lists key information elements. Every phrase contributes meaning without redundancy. However, it could be slightly more structured by separating the core function from optional features for better clarity.

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

Completeness2/5

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

Given the complexity of a table metadata tool with 3 parameters, 0% schema coverage, no annotations, and no output schema, the description is insufficient. It covers the basic purpose and hints at one parameter but lacks details on behavior, return values, error handling, and complete parameter documentation. This leaves the agent with significant uncertainty about tool invocation.

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?

With 0% schema description coverage, the schema provides no parameter documentation. The description mentions 'optionally statistics like row count and size' which hints at the 'include_statistics' parameter's purpose, but doesn't explain the 'table' or 'schema_name' parameters. It adds some value for one parameter but doesn't fully compensate for the coverage gap, leaving two parameters undocumented.

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

Purpose4/5

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

The description clearly states the verb ('Get') and resource ('detailed information about a specific table'), specifying what information is included (columns, constraints, indexes, statistics). It distinguishes from siblings like 'get-schema' by focusing on a single table's details rather than overall schema. However, it doesn't explicitly differentiate from 'query-table' which might also provide table information.

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 implies usage for obtaining comprehensive table metadata, including optional statistics. It suggests when to use it (for detailed table analysis) but doesn't explicitly state when NOT to use it or provide clear alternatives among siblings like 'get-schema' for broader schema overview or 'query-table' for data retrieval. No prerequisites or exclusions are mentioned.

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

insert-dataC

Insert new records into a table. Supports single or multiple records, conflict resolution (ignore/update), and returning inserted data.

ParametersJSON Schema
NameRequiredDescriptionDefault
tableYes
dataYes
on_conflictNoerror
conflict_columnsNo
returningNo

TDQS

C2.9/5.0
Behavior2/5

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

With no annotations provided, the description carries the full burden of behavioral disclosure. It mentions conflict resolution options and returning data, which adds some context beyond basic insertion. However, it lacks critical details such as required permissions, potential side effects (e.g., data integrity impacts), error handling beyond conflicts, or performance considerations like rate limits, making it insufficient for a mutation 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, well-structured sentence that front-loads the core purpose ('Insert new records into a table') and efficiently lists key features without redundancy. Every phrase adds value, such as clarifying record types and conflict handling, making it appropriately sized and easy to parse.

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

Completeness2/5

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

Given the tool's complexity (5 parameters, mutation operation, no annotations, and no output schema), the description is incomplete. It covers basic functionality but lacks details on error cases, output format, dependencies (e.g., table existence), and comparisons with siblings like 'update-data'. For a data insertion tool with significant behavioral implications, this leaves the agent under-informed.

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 description coverage is 0%, so the description must compensate for undocumented parameters. It mentions 'single or multiple records' (hinting at the 'data' parameter), 'conflict resolution (ignore/update)' (hinting at 'on_conflict'), and 'returning inserted data' (hinting at 'returning'), covering 3 of 5 parameters. However, it omits 'table' and 'conflict_columns', and doesn't provide detailed semantics like format or constraints, leaving gaps in understanding.

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

Purpose4/5

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

The description clearly states the action ('Insert new records') and target resource ('into a table'), which is specific and unambiguous. It distinguishes from siblings like 'delete-data' and 'update-data' by focusing on insertion rather than modification or removal. However, it doesn't explicitly differentiate from 'execute-query' which might also insert data, leaving slight room for improvement.

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

Usage Guidelines2/5

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

The description mentions 'Supports single or multiple records, conflict resolution (ignore/update), and returning inserted data,' which implies usage scenarios but doesn't provide explicit guidance on when to use this tool versus alternatives like 'update-data' or 'execute-query'. No context about prerequisites, exclusions, or sibling tool comparisons is included, leaving the agent with minimal direction.

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

query-tableC

Query data from a specific table with filtering, pagination, and sorting. Supports WHERE conditions with exact matches, arrays (IN), and LIKE patterns.

ParametersJSON Schema
NameRequiredDescriptionDefault
tableYes
columnsNo
whereNo
paginationNo
sortNo

TDQS

C2.8/5.0
Behavior2/5

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

No annotations are provided, so the description carries the full burden. It mentions filtering capabilities (WHERE conditions with exact matches, arrays, and LIKE patterns) but omits critical behavioral details: whether this is a read-only operation, potential rate limits, error handling, or what the return format looks like (especially without an output schema). For a query tool with 5 parameters and no annotations, this is insufficient.

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, well-structured sentence that efficiently lists key features without redundancy. It's front-loaded with the core purpose and follows with supporting details. Every word earns its place, making it highly concise.

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

Completeness2/5

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

Given the complexity (5 parameters with nested objects, no annotations, no output schema), the description is incomplete. It lacks details on behavioral traits (e.g., read-only nature, error responses), full parameter semantics, and output format. For a query tool that likely returns data, the absence of output schema or description of return values is a significant gap.

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

Parameters2/5

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

Schema description coverage is 0%, so the schema provides no parameter documentation. The description adds some value by mentioning filtering, pagination, and sorting, which map to 'where', 'pagination', and 'sort' parameters, and specifies support for exact matches, arrays (IN), and LIKE patterns for 'where'. However, it doesn't explain 'table' or 'columns' parameters, leaving 2 of 5 parameters undocumented, failing to compensate for the low coverage.

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

Purpose4/5

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

The description clearly states the tool's purpose: 'Query data from a specific table with filtering, pagination, and sorting.' It specifies the verb ('query'), resource ('data from a specific table'), and key capabilities. However, it doesn't explicitly differentiate from sibling tools like 'execute-query' or 'get-table-info', which prevents a perfect score.

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

Usage Guidelines2/5

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

The description provides no guidance on when to use this tool versus alternatives. With siblings like 'execute-query' (likely for raw SQL) and 'get-table-info' (likely for metadata), the agent has no indication of the appropriate context for this structured query tool. No exclusions or prerequisites are mentioned.

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

update-dataB

Update existing records in a table. Requires WHERE conditions for safety. Supports complex WHERE clauses and returns updated records.

ParametersJSON Schema
NameRequiredDescriptionDefault
tableYes
dataYes
whereYes
returningNo

TDQS

B3.1/5.0
Behavior2/5

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

With no annotations provided, the description carries full burden but offers limited behavioral insight. It mentions safety requirements (WHERE conditions) and return behavior (returns updated records), but doesn't cover critical aspects like permissions needed, whether updates are reversible, rate limits, error handling, or transaction implications. For a mutation tool with zero annotation coverage, this leaves significant gaps in understanding its behavior.

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

Conciseness4/5

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

The description is efficiently structured in two sentences that get straight to the point: first states core functionality and safety requirement, second adds capabilities and return behavior. There's no wasted text, though it could be slightly more front-loaded by mentioning the return behavior earlier.

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

Completeness2/5

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

Given this is a mutation tool with 4 parameters (including complex nested objects), 0% schema coverage, no annotations, and no output schema, the description is insufficiently complete. It doesn't explain what 'data' should contain, how 'where' clauses are structured, what 'returning' controls, or provide examples. The agent would struggle to use this tool correctly without significant additional context.

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?

With 0% schema description coverage, the description must compensate but only partially does so. It mentions 'WHERE conditions' (mapping to 'where' parameter) and 'returns updated records' (hinting at 'returning'), but doesn't explain 'table' or 'data' parameters at all. The description adds some meaning but doesn't fully address the four parameters, especially given the complex nested object structure indicated in context signals.

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

Purpose4/5

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

The description clearly states the action ('Update existing records') and resource ('in a table'), making the purpose immediately understandable. It distinguishes from siblings like 'insert-data' (creates new) and 'delete-data' (removes), but doesn't explicitly contrast with 'query-table' or 'execute-query' which might also modify data.

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 provides some guidance by stating 'Requires WHERE conditions for safety' and mentioning support for 'complex WHERE clauses', which implies when to use it (for updates with conditions). However, it doesn't explicitly say when NOT to use it or name alternatives like 'insert-data' for new records or 'execute-query' for other operations, leaving usage context somewhat implied.

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. 8 tool updates
    • First observedconnection-status
    • First observeddelete-data
    • First observedexecute-query
    • First observedget-schema
    • First observedget-table-info
    • First observedinsert-data
    • First observedquery-table
    • First observedupdate-data
Install Server
RayrunBuild, deploy, and operate MCP servers without becoming an infrastructure team.ray.runAd

TDQS

B3.4/5.0
Disambiguation4/5

Most tools have distinct purposes, but there is some overlap between 'execute-query' and 'query-table' that could cause confusion. 'execute-query' handles general SQL operations, while 'query-table' is specifically for querying tables with filtering, but both can be used for SELECT queries, potentially leading to misselection. Other tools like 'insert-data', 'update-data', and 'delete-data' are clearly differentiated by their CRUD operations.

Naming Consistency5/5

Tool names follow a consistent verb-noun pattern with hyphens throughout, such as 'execute-query', 'get-schema', and 'update-data'. All tools adhere to this naming convention, making them predictable and easy to understand. There are no deviations or mixed styles like camelCase or snake_case, ensuring high readability.

Tool Count5/5

With 8 tools, the count is well-scoped for a PostgreSQL server, covering essential database operations like connection management, CRUD, schema inspection, and query execution. Each tool serves a clear purpose without redundancy, and the number is neither too thin nor overwhelming, fitting typical server needs in the 3-15 tool range.

Completeness4/5

The tool set provides comprehensive coverage for core PostgreSQL operations, including connection status, schema retrieval, CRUD operations, and query execution. Minor gaps exist, such as the lack of tools for managing database objects (e.g., creating/dropping tables or indexes) or handling transactions, but agents can work around these using 'execute-query' for most missing functions.

Maintenance

ActivityInactive
ResponsivenessSyncing

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

  • Enhanced PostgreSQL MCP Server

    GarethCott
    A
    license
    Not graded
    quality
    F
    maintenance
    A Model Context Protocol server providing both read and write access to PostgreSQL databases, enabling LLMs to query data, modify records, and manage database schemas.
    309
    10
    MIT

  • SQL MCP Server

    t3ta
    A
    license
    Not graded
    quality
    C
    maintenance
    A TypeScript implementation of a Model Context Protocol server that enables language models to securely query PostgreSQL databases, including those behind SSH bastion tunnels.
    24
    1
    MIT

  • PostgreSQL MCP Server

    ahmedmustahid
    A
    license
    Not graded
    quality
    F
    maintenance
    A Model Context Protocol server providing dual transport (HTTP and Stdio) access to PostgreSQL databases, allowing AI assistants to query databases and fetch schema information through natural language.
    101
    31
    MIT

  • pg-mcp-server

    stuzero
    A
    license
    Not graded
    quality
    D
    maintenance
    A Model Context Protocol server for PostgreSQL databases that enables AI agents to connect, query, and explore multiple databases with schema discovery and extension context.
    540
    MIT

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/cesarvarela/postgres-mcp'

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