Skip to main content
Glama
yugui923

db-connect-mcp

by yugui923
OverviewSchemaRelated ServersScoreDiscussions
Python
Remote

db-connect-mcp - Multi-Database MCP Server

CI CodeQL codecov OpenSSF Scorecard License: MIT

A read-only MCP (Model Context Protocol) server for exploratory data analysis across multiple database systems. This server provides safe, read-only access to PostgreSQL, MySQL, and ClickHouse databases with comprehensive analysis capabilities.

Demo

db-connect-mcp demo

Related MCP server: mcp-postgres

Quick Start

  1. Install:

    pip install db-connect-mcp

  2. Add to Claude Desktop claude_desktop_config.json:

    {
  "mcpServers": {
    "db-connect": {
      "command": "python",
      "args": ["-m", "db_connect_mcp"],
      "env": {
        "DATABASE_URL": "postgresql://user:pass@localhost:5432/mydb"
      }
    }
  }
}

  3. Restart Claude Desktop and start querying your database!

Note: Using python -m db_connect_mcp ensures the command works even if Python's Scripts directory isn't in your PATH.

Features

🗄️ Multi-Database Support

  • PostgreSQL - Full support with advanced metadata and statistics

  • MySQL - Complete support for MySQL and MariaDB databases

  • ClickHouse - Support for analytical workloads and columnar storage

🔍 Database Exploration

  • List schemas - View all schemas in the database

  • List tables - See all tables with metadata (size, row counts, comments)

  • Describe tables - Get detailed column information, indexes, and constraints

  • View relationships - Understand foreign key relationships between tables

📊 Data Analysis

  • Column profiling - Statistical analysis of column data

    • Basic statistics (count, unique values, nulls)

    • Numeric statistics (mean, median, std dev, quartiles)

    • Value frequency distribution

    • Cardinality analysis

  • Data sampling - Preview table data with configurable limits

  • Custom queries - Execute read-only SQL queries safely

  • Object search - Find schemas, tables, views, columns, and indexes without loading the full catalog

  • Query plans - Inspect estimated plans or opt into EXPLAIN ANALYZE where supported

🔒 Safety Features

  • Read-only enforcement - All connections are read-only at multiple levels

  • Query validation - Only SELECT and WITH queries are allowed

  • Automatic limits - Queries are automatically limited to prevent large result sets

  • Connection string safety - Automatically adds read-only parameters

  • Database-specific safety - Each adapter implements appropriate safety measures

🔭 Observability

db-connect-mcp inherits the MCP SDK's built-in OpenTelemetry server instrumentation. The API is a no-op until the launching process configures an SDK and exporter. Review exporter sampling and redaction before production use, because database identifiers and error details may be sensitive.

💡 Best Practices

Tip: db-connect-mcp works best with databases that have proper comments on tables and columns. When your database includes descriptive comments, the MCP server can provide richer context to AI assistants, leading to better understanding of your data model and more accurate query suggestions.

Adding comments in PostgreSQL:

COMMENT ON TABLE users IS 'Registered user accounts with profile information';
COMMENT ON COLUMN users.email IS 'Primary email address, used for authentication';
COMMENT ON COLUMN users.is_verified IS 'Whether email has been verified via confirmation link';

Adding comments in MySQL:

ALTER TABLE users COMMENT = 'Registered user accounts with profile information';
ALTER TABLE users MODIFY COLUMN email VARCHAR(255) COMMENT 'Primary email address, used for authentication';

The server automatically retrieves and displays these comments when describing tables, helping AI assistants understand the purpose and semantics of your data.

🔐 SSH Tunnel Support

  • Secure remote access - Connect to databases behind firewalls via SSH tunnels

  • Automatic tunnel management - Tunnel lifecycle handled transparently (start, health check, restart, cleanup)

  • Reliable native forwarding - Paramiko SSHClient transport with target preflight and stable-port recovery

  • Flexible authentication - Password or private key based SSH authentication

  • Any database type - Works with PostgreSQL, MySQL, and ClickHouse through the same tunnel

See the SSH Tunnel Guide for configuration details.

Installation

Prerequisites

  • Python 3.10 or higher

  • A database: PostgreSQL (9.6+), MySQL/MariaDB (5.7+/10.2+), or ClickHouse

Install via pip

pip install db-connect-mcp

That's it! The package is now ready to use.

For developers: See Development Guide for setting up a development environment.

Configuration

Create a .env file with your database connection string:

DATABASE_URL=your_database_connection_string_here

The server automatically detects the database type and adds appropriate read-only parameters.

Connection String Examples

The server now provides more flexible and secure URL handling:

  • Automatic driver detection: Async drivers are automatically added if not specified

  • JDBC URL support: JDBC prefixes are automatically handled

    • jdbc:postgresql://... → postgresql+asyncpg://...

    • jdbc:mysql://... → mysql+aiomysql://...

    • Works with all dialect variations (e.g., jdbc:postgres://, jdbc:mariadb://)

  • Database dialect variations: Common variations are automatically normalized

    • PostgreSQL: postgresql, postgres, pg, psql, pgsql

    • MySQL/MariaDB: mysql, mariadb, maria

    • ClickHouse: clickhouse, ch, click

  • Allowlist-based parameter filtering: Only known-safe parameters are preserved

  • Database-specific parameters: Each database type has its own set of supported parameters

  • Robust parsing: Handles various URL formats gracefully

PostgreSQL:

# Simple URL (driver automatically added)
DATABASE_URL=postgresql://user:password@localhost:5432/mydb

# Common variations (all normalized to postgresql+asyncpg)
DATABASE_URL=postgres://user:pass@host:5432/db  # Heroku, AWS RDS style
DATABASE_URL=pg://user:pass@host:5432/db         # Short form
DATABASE_URL=psql://user:pass@host:5432/db       # CLI style

# JDBC URLs (automatically converted)
DATABASE_URL=jdbc:postgresql://user:pass@host:5432/db  # From Java apps
DATABASE_URL=jdbc:postgres://user:pass@host:5432/db    # JDBC with variant

# With explicit async driver
DATABASE_URL=postgresql+asyncpg://user:pass@host:5432/db

# With supported parameters (see list below)
DATABASE_URL=postgres://user:pass@host:5432/db?application_name=myapp&connect_timeout=10

Supported PostgreSQL Parameters:

  • application_name - Identifies your app in pg_stat_activity (useful for monitoring)

  • connect_timeout - Connection timeout in seconds

  • command_timeout - Default timeout for operations

  • ssl / sslmode - SSL connection requirements (automatically converted for asyncpg compatibility)

  • server_settings - Server settings dictionary

  • options - Command-line options to send to server

  • Performance tuning: prepared_statement_cache_size, max_cached_statement_lifetime, etc.

MySQL/MariaDB:

# Simple URL (driver automatically added)
DATABASE_URL=mysql://root:password@localhost:3306/mydb

# MariaDB URLs (normalized to mysql+aiomysql)
DATABASE_URL=mariadb://user:pass@host:3306/db    # MariaDB style
DATABASE_URL=maria://user:pass@host:3306/db      # Short form

# JDBC URLs (automatically converted)
DATABASE_URL=jdbc:mysql://user:pass@host:3306/db     # From Java apps
DATABASE_URL=jdbc:mariadb://user:pass@host:3306/db   # JDBC MariaDB

# With explicit async driver
DATABASE_URL=mysql+aiomysql://user:pass@host:3306/db

# With charset (critical for proper Unicode support)
DATABASE_URL=mariadb://user:pass@remote.host:3306/db?charset=utf8mb4

Supported MySQL Parameters:

  • charset - Character encoding (e.g., utf8mb4) - critical for data integrity

  • use_unicode - Enable Unicode support

  • connect_timeout, read_timeout, write_timeout - Various timeouts

  • autocommit - Transaction autocommit mode

  • init_command - Initial SQL command to run

  • sql_mode - SQL mode settings

  • time_zone - Time zone setting

ClickHouse:

# Simple URL (driver automatically added)
DATABASE_URL=clickhouse://default:@localhost:9000/default

# Short forms (normalized to clickhouse+asynch)
DATABASE_URL=ch://user:pass@host:9000/db         # Short form
DATABASE_URL=click://user:pass@host:9000/db      # Alternative

# JDBC URLs (automatically converted)
DATABASE_URL=jdbc:clickhouse://user:pass@host:9000/db  # From Java apps
DATABASE_URL=jdbc:ch://user:pass@host:9000/db         # JDBC with short form

# With explicit async driver
DATABASE_URL=clickhouse+asynch://user:pass@host:9000/db

# With performance settings
DATABASE_URL=ch://user:pass@host:9000/db?timeout=60&max_threads=4

Supported ClickHouse Parameters:

  • database - Default database selection

  • timeout, connect_timeout, send_receive_timeout - Various timeouts

  • compress, compression - Enable compression

  • max_block_size, max_threads - Performance tuning

Note:

  • SSL parameters (ssl, sslmode) are automatically converted to the correct format for asyncpg

  • Certificate file parameters (sslcert, sslkey, sslrootcert) are filtered out as they can cause compatibility issues

  • Only parameters known to work with async drivers are preserved

Usage

Running the Server

# Run the server (works everywhere, no PATH configuration needed)
python -m db_connect_mcp

# With environment variable
DATABASE_URL="postgresql://user:pass@host:5432/db" python -m db_connect_mcp

Note: Using python -m db_connect_mcp works regardless of whether Python's Scripts directory is in your PATH.

Using with Claude Code

Add the MCP server to your project's .mcp.json:

claude mcp add --transport stdio db-connect --scope project \
  --env DATABASE_URL=postgresql://user:pass@host:5432/db \
  -- python -m db_connect_mcp

Or manually create .mcp.json in your project root. Below are examples for each supported database:

PostgreSQL:

{
  "mcpServers": {
    "db-connect-mcp": {
      "command": "python",
      "args": ["-m", "db_connect_mcp"],
      "env": {
        "DATABASE_URL": "postgresql+asyncpg://user:pass@host:5432/mydb"
      }
    }
  }
}

MySQL:

{
  "mcpServers": {
    "db-connect-mcp": {
      "command": "python",
      "args": ["-m", "db_connect_mcp"],
      "env": {
        "DATABASE_URL": "mysql+aiomysql://user:pass@host:3306/mydb"
      }
    }
  }
}

ClickHouse:

{
  "mcpServers": {
    "db-connect-mcp": {
      "command": "python",
      "args": ["-m", "db_connect_mcp"],
      "env": {
        "DATABASE_URL": "clickhouse+asynch://default:@host:9000/default"
      }
    }
  }
}

PostgreSQL via SSH tunnel (database behind a firewall, reachable only through a bastion host):

{
  "mcpServers": {
    "db-connect-mcp": {
      "command": "python",
      "args": ["-m", "db_connect_mcp"],
      "env": {
        "DATABASE_URL": "postgresql+asyncpg://user:pass@db-internal:5432/mydb",
        "SSH_HOST": "bastion.example.com",
        "SSH_PORT": "22",
        "SSH_USERNAME": "deployer",
        "SSH_PRIVATE_KEY_PATH": "/home/user/.ssh/id_rsa"
      }
    }
  }
}

MySQL via SSH tunnel:

{
  "mcpServers": {
    "db-connect-mcp": {
      "command": "python",
      "args": ["-m", "db_connect_mcp"],
      "env": {
        "DATABASE_URL": "mysql+aiomysql://user:pass@db-internal:3306/mydb",
        "SSH_HOST": "bastion.example.com",
        "SSH_PORT": "22",
        "SSH_USERNAME": "deployer",
        "SSH_PASSWORD": "secret"
      }
    }
  }
}

Multiple databases (each MCP server instance connects to one database):

{
  "mcpServers": {
    "postgres-prod": {
      "command": "python",
      "args": ["-m", "db_connect_mcp"],
      "env": {
        "DATABASE_URL": "postgresql+asyncpg://user:pass@pg-host:5432/prod"
      }
    },
    "mysql-analytics": {
      "command": "python",
      "args": ["-m", "db_connect_mcp"],
      "env": {
        "DATABASE_URL": "mysql+aiomysql://user:pass@mysql-host:3306/analytics"
      }
    }
  }
}

After creating .mcp.json, restart Claude Code and verify with /mcp. You should see db-connect-mcp listed with all available tools.

Tip: Instead of SSH_PRIVATE_KEY_PATH, you can use SSH_PRIVATE_KEY to pass the private key content directly as a string (raw PEM or base64-encoded PEM). This is useful in CI/CD or cloud environments where mounting key files is impractical.

See the SSH Tunnel Guide for full tunnel configuration reference.

Using with Claude Desktop

Add the server to your Claude Desktop configuration (claude_desktop_config.json):

{
  "mcpServers": {
    "db-connect": {
      "command": "python",
      "args": ["-m", "db_connect_mcp"],
      "env": {
        "DATABASE_URL": "postgresql+asyncpg://user:pass@host:5432/db"
      }
    }
  }
}

The same database URL formats and SSH tunnel environment variables shown in the Claude Code examples above work identically with Claude Desktop.

For development: See Development Guide for running from source with uv.

Database Feature Support

Feature

PostgreSQL

MySQL

ClickHouse

Schemas

✅ Full

✅ Full

✅ Full

Tables

✅ Full

✅ Full

✅ Full

Views

✅ Full

✅ Full

✅ Full

Indexes

✅ Full

✅ Full

⚠️ Limited

Foreign Keys

✅ Full

✅ Full

❌ No

Constraints

✅ Full

✅ Full

⚠️ Limited

Table Size

✅ Exact

✅ Exact

✅ Exact

Row Count

✅ Exact

✅ Exact

✅ Exact

Column Stats

✅ Full

✅ Full

✅ Full

Sampling

✅ Full

✅ Full

✅ Full

MCP Resources

Modern MCP clients can discover database context as private, cache-aware JSON resources in addition to calling tools:

  • db-connect://database — database identity, dialect, and capabilities

  • db-connect://schema/{schema} — schema counts and metadata

  • db-connect://table/{schema}/{table} — columns, indexes, constraints, and comments

The schema and table forms are also advertised as resource templates for direct access when the identifier is already known.

Resource catalogs are URI-sorted and cursor-paginated in pages of 100. Cursors are tied to a catalog snapshot; if schemas or tables change between pages, the server asks the client to restart pagination instead of returning an inconsistent traversal.

Available Tools

All tools publish JSON Schema input and output contracts, read-only behavior annotations, and machine-readable structured results. The same result remains available as JSON text for clients that do not yet consume MCP structured content. Structured list results use an items envelope while their legacy text form remains a JSON array.

get_database_info

Get database metadata, including the dialect, version, connection details, read-only status, and capabilities.

list_schemas

List all schemas in the database.

list_tables

List all tables in a schema with metadata.

  • Parameters:

    • schema (optional): Schema name (default: "public")

describe_table

Get detailed information about a table.

  • Parameters:

    • table: Name of the table

    • schema (optional): Schema name (default: "public")

analyze_column

Analyze a column with statistics and distribution.

  • Parameters:

    • table: Name of the table

    • column: Name of the column

    • schema (optional): Schema name (default: "public")

sample_data

Get a sample of data from a table.

  • Parameters:

    • table: Name of the table

    • schema (optional): Schema name (default: "public")

    • limit (optional): Number of rows (default: 100, max: 1000)

execute_query

Execute a read-only SQL query.

  • Parameters:

    • query: SQL query (must be SELECT or WITH)

    • limit (optional): Maximum rows (default: 1000, max: 10000)

get_table_relationships

Get foreign key relationships for a table.

  • Parameters:

    • table: Name of the table

    • schema (optional): Schema name (default: "public")

explain_query

Get a database-specific query execution plan.

  • Parameters:

    • query: SQL query to explain

    • analyze (optional): Execute the query and include actual runtime statistics (default: false)

search_objects

Search schemas, tables, views, columns, and indexes with progressive detail.

  • Parameters:

    • pattern: SQL LIKE pattern, such as %user%

    • object_types (optional): Object types to include

    • detail_level (optional): names, summary, or full (default: summary)

    • schema (optional): Restrict the search to a schema

    • table (optional): Restrict column and index searches to a table

    • limit (optional): Maximum matches (default: 100, max: 1000)

Example Usage in Claude

Once configured, you can use the server in Claude:

"Can you analyze my database and tell me about the table structure?"

"Show me the relationships between tables in the public schema"

"What's the distribution of values in the users.created_at column?"

"Give me a sample of data from the orders table"

"Run this query: SELECT COUNT(*) FROM users WHERE created_at > '2024-01-01'"

Database-Specific Examples

Working with PostgreSQL:

"List all schemas except system ones"
"Show me the foreign key relationships in the sales schema"
"Analyze the performance of indexes on the products table"

Working with MySQL:

"What storage engines are being used in my database?"
"Show me all tables in the information_schema"
"Analyze the customer_orders table structure"

Working with ClickHouse:

"Show me the partitions for the events table"
"What's the compression ratio for the analytics.clicks table?"
"Sample 1000 rows from the metrics table"

Safety and Security

  • Read-only by design: The server enforces read-only access at multiple levels:

    • Connection string parameters

    • Session-level settings

    • Query validation

  • No data modification: INSERT, UPDATE, DELETE, CREATE, DROP, and other modification statements are blocked

  • Query limits: All queries are automatically limited to prevent excessive resource usage

  • No sensitive operations: No access to system catalogs or administrative functions

Development

For detailed development setup, testing, and contribution guidelines, see the Development Guide.

Project Structure

db-connect-mcp/
├── src/
│   └── db_connect_mcp/
│       ├── adapters/         # Database-specific adapters
│       │   ├── __init__.py
│       │   ├── base.py      # Base adapter interface
│       │   ├── postgresql.py # PostgreSQL adapter
│       │   ├── mysql.py     # MySQL adapter
│       │   └── clickhouse.py # ClickHouse adapter
│       ├── core/            # Core functionality
│       │   ├── __init__.py
│       │   ├── connection.py # Database connection management
│       │   ├── executor.py  # Query execution
│       │   ├── inspector.py # Metadata inspection
│       │   ├── analyzer.py  # Statistical analysis
│       │   └── tunnel.py   # SSH tunnel management
│       ├── models/          # Data models
│       │   ├── __init__.py
│       │   ├── capabilities.py # Database capabilities
│       │   ├── config.py    # Configuration models
│       │   ├── database.py  # Database models
│       │   ├── query.py     # Query models
│       │   ├── statistics.py # Statistics models
│       │   └── table.py     # Table metadata models
│       ├── __init__.py
│       ├── __main__.py      # Module entry point
│       └── server.py        # Main MCP server implementation
├── tests/
│   ├── unit/            # Unit tests (mocked)
│   ├── module/          # Module tests (single component + DB)
│   ├── integration/     # Integration tests (full stack)
│   └── conftest.py      # Shared fixtures
├── .env.example         # Example environment configuration
├── pyproject.toml      # Project dependencies and console scripts
└── README.md          # This file

Architecture

The server uses an adapter pattern to support multiple database systems:

  • Adapters: Each database type has its own adapter that implements database-specific functionality

  • Core: Shared functionality for connection management, query execution, and metadata inspection

  • Models: Pydantic models for type safety and validation

  • Server: MCP server implementation that routes requests to appropriate components

Running Tests

# Start local test database (PostgreSQL 17 with sample data)
cd tests/docker && docker-compose up -d && cd ../..

# Run all tests in parallel (preferred - 6 workers)
uv run pytest -n 6

# Run specific test modules
uv run pytest tests/module/test_inspector.py -v -n 6
uv run pytest tests/integration/ -v -n 6

# Stop test database
cd tests/docker && docker-compose down && cd ../..

# Reset database (clean slate with fresh data)
cd tests/docker && docker-compose down -v && docker-compose up -d && cd ../..

Local Test Database:

  • PostgreSQL 17 with 50K+ rows of sample data across 7 tables

  • Automatically initialized via Docker Compose

  • No cloud database or .env configuration required

  • See Docker Setup for details

See the Development Guide and Testing Guide for detailed testing instructions.

Troubleshooting

Connection Issues

  • Verify your DATABASE_URL is correct and includes the appropriate driver

  • Check network connectivity to the database

  • Ensure the database user has appropriate read permissions

  • For PostgreSQL: Check if SSL is required (?ssl=require)

  • For MySQL: Verify charset settings (?charset=utf8mb4)

  • For ClickHouse: Check port (default is 9000 for native, 8123 for HTTP)

Database-Specific Issues

PostgreSQL:

  • Ensure asyncpg driver is specified for async operations

  • SSL certificates may be required for cloud databases

MySQL/MariaDB:

  • Use aiomysql driver for async support

  • Check MySQL version compatibility (5.7+ or MariaDB 10.2+)

  • Verify charset and collation settings

ClickHouse:

  • Use asynch driver for async operations

  • Note that ClickHouse has limited support for foreign keys and constraints

  • Some statistical functions may not be available

Permission Errors

  • The database user needs at least SELECT permissions on the schemas/tables you want to analyze

  • Some statistical functions may require additional permissions

  • ClickHouse may require specific permissions for system tables

Large Result Sets

  • Use the limit parameter to control result size

  • The server automatically limits results to prevent memory issues

  • For large analyses, consider using more specific queries

Author

Created by Yuri Gui.

Contributing

Contributions are welcome! The server is designed to be read-only and safe by default. Any new features should maintain these safety guarantees.

License

MIT License - See LICENSE file for details

Available Tools

10 tools
analyze_columnB

Get comprehensive column statistics including percentiles and distributions

ParametersJSON Schema
NameRequiredDescriptionDefault
tableYesTable name
columnYesColumn name
schemaNoSchema name (optional)

TDQS

B3.3/5.0
Behavior2/5

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

No annotations are provided, and the description does not disclose behavioral traits such as read-only nature, performance implications, or data requirements. The description only states the output but not the side effects or constraints.

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 sentence that front-loads the core purpose. It is concise, though it could benefit from a bit more detail without losing brevity.

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 lack of output schema and annotations, the description is incomplete. It does not specify the format of the returned statistics, what additional metrics are included, or potential size of results.

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% with clear parameter descriptions, so the baseline is 3. The tool description adds no additional meaning beyond the schema, but does not contradict or mislead.

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 comprehensive column statistics, specifically highlighting percentiles and distributions, which distinguishes it from sibling tools like describe_table (metadata) or sample_data (rows).

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 statistical analysis but does not explicitly contrast with sibling tools nor provide conditions for when to use this tool over alternatives like describe_table or sample_data.

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

describe_tableC

Get comprehensive table information including columns, indexes, and constraints

ParametersJSON Schema
NameRequiredDescriptionDefault
tableYesTable name
schemaNoSchema name (optional)

TDQS

C2.9/5.0
Behavior2/5

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

No annotations are provided, so the description must disclose behavioral traits. It states what is returned but does not mention whether it is a live query, if it is read-only, or any permissions needed. Mutability and safety are not addressed.

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, clear sentence with no wasted words. It is front-loaded with the purpose but could include a sentence about return format or common use cases without being too long.

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 has two parameters (one required) and no output schema, the description is adequate but lacks details on output structure, pagination, or limitations like schema wildcards. It covers the basics but leaves gaps.

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% with both parameters described in the input schema. The description adds no additional meaning beyond the schema, so baseline score of 3 is appropriate.

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 returns comprehensive table information including columns, indexes, and constraints. It distinguishes from siblings like list_tables and get_table_relationships, but does not fully differentiate from analyze_column which also covers columns.

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?

No explicit guidance on when to use this tool versus alternatives. It does not describe prerequisites, after which actions it is useful, or situations to avoid.

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

execute_queryA

Execute a read-only SQL query (SELECT, WITH, EXPLAIN)

ParametersJSON Schema
NameRequiredDescriptionDefault
queryYesSQL query to execute
limitNoMaximum number of rows to return (default: 1000)

TDQS

A3.7/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 correctly identifies the tool as read-only, which is a key behavioral trait. However, it omits details like error handling, return format, timeout limits, or behavior when limit is exceeded.

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?

Single sentence that front-loads the action and resource. No wasted words, efficient and clear.

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 simple tool with no output schema and no annotations, the description is minimally adequate. It covers the read-only constraint but lacks details on return format, error conditions, or integration with sibling tools.

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% (both 'query' and 'limit' have descriptions). The tool description adds no additional parameter-specific meaning, so baseline 3 is appropriate.

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 executes read-only SQL queries, listing specific SQL types (SELECT, WITH, EXPLAIN). It differentiates from sibling tools like 'explain_query' and 'sample_data' by specifying the scope of operation.

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 read-only usage but does not explicitly exclude write operations or compare to sibling tools like 'explain_query' (which likely returns execution plans). No guidance on when to choose this over alternatives.

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

explain_queryB

Get query execution plan to analyze performance

ParametersJSON Schema
NameRequiredDescriptionDefault
queryYesSQL query to explain
analyzeNoWhether to execute the query (EXPLAIN ANALYZE)

TDQS

B3.1/5.0
Behavior2/5

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

The description does not disclose the potential side effect of the analyze parameter: when set to true, the tool executes the query (EXPLAIN ANALYZE), which can modify state if the query is a write operation. With no annotations, this omission is critical.

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, concise sentence that immediately conveys the tool's purpose with no unnecessary words. It is well front-loaded.

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 lack of an output schema and annotations, the description should cover more behavioral aspects, especially the analyze flag's implications. The tool is simple, but the omission of side effects makes it incomplete.

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?

Schema coverage is 100% with descriptions for both parameters. The description adds value by linking the query parameter to performance analysis, but does not elaborate on the analyze parameter beyond its existence in the schema.

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 retrieves a 'query execution plan' for performance analysis, distinguishing it from sibling tools like execute_query (which runs queries) and analyze_column (which focuses on columns). However, it does not explicitly compare itself to siblings.

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?

No guidance is provided on when to use this tool versus alternatives, such as execute_query or sample_data. The description implies usage for analyzing query performance, but lacks explicit when-to-use or when-not-to-use criteria.

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

get_database_infoA

Get database information including version, size, and capabilities

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 provided, and description only states output type. Lacks details on behavioral traits like read-only nature, permissions, or side effects. For a tool with no annotations, more behavioral context is needed.

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?

Single efficient sentence, no waste. Front-loaded with core purpose.

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?

Adequate for a simple info tool with no parameters, but missing details on what 'capabilities' specifically includes. Could leverage sibling contexts to be more precise.

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?

No parameters exist (0 params), so baseline is 4. Description adds no param info, but that is acceptable as schema coverage is 100%.

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?

Description clearly states 'Get database information including version, size, and capabilities' with a specific verb and resource. It distinguishes from sibling tools like 'describe_table' and 'analyze_column' which target specific aspects.

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?

Implied usage for general database overview, but no explicit guidance on when to use versus alternatives like 'list_schemas' or 'get_table_relationships'. No when-not-to-use or prerequisites mentioned.

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

get_table_relationshipsB

Get foreign key relationships for a table

ParametersJSON Schema
NameRequiredDescriptionDefault
tableYesTable name
schemaNoSchema name (optional)

TDQS

B3.4/5.0
Behavior2/5

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

No annotations provided. Description does not disclose behavioral traits such as performance, required permissions, or whether it is read-only. Agent must infer from tool name.

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?

Single sentence, to the point, no unnecessary words.

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?

Tool is simple; schema covers parameters. Description does not explain return value structure, but output schema is absent. Adequate for a straightforward retrieval operation.

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?

Input schema has 100% coverage with descriptions for both parameters. Description does not add extra meaning beyond 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?

Description clearly states the tool retrieves foreign key relationships for a table, using a specific verb and resource. It distinguishes from sibling tools like analyze_column and describe_table.

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?

No guidance on when to use this tool versus alternatives. Does not state prerequisites or exclusion conditions.

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

list_schemasA

List all schemas/databases in the database instance

ParametersJSON Schema
NameRequiredDescriptionDefault

No parameters

TDQS

A3.7/5.0
Behavior3/5

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

Without annotations, the description should explicitly state it is a read-only operation. It implies listing but does not disclose behavior beyond that.

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?

A single, concise sentence that immediately conveys the tool's purpose.

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 zero-parameter list tool, the description is adequate but lacks details on return format or potential nuances.

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?

No parameters exist, so baseline 4. The description does not add parameter-specific info, but schema coverage is 100%.

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 it lists all schemas/databases, which is a specific verb+resource. It distinguishes itself from sibling tools like list_tables or describe_table.

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?

No guidance on when to use this tool vs alternatives. No context or prerequisites mentioned.

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

list_tablesB

List all tables and views in a schema

ParametersJSON Schema
NameRequiredDescriptionDefault
schemaNoSchema name (optional, uses default if not specified)
include_viewsNoWhether to include views (default: true)

TDQS

B3.3/5.0
Behavior2/5

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

No annotations provided, so description should disclose behavioral traits. It only repeats parameter info (optional schema, include_views default true) but does not mention performance, authentication, or side effects. For a simple listing tool, more transparency about output format or limitations would help.

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?

Extremely concise: one sentence with no wasted words. Every word serves a purpose.

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 no annotations and no output schema, the description is minimal but still functional. It could be more complete by specifying the output format (e.g., list of names) or clarifying if views are included separately. However, with only 2 simple params, it is adequate.

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 100%, so baseline is 3. Description adds no extra meaning beyond what the input schema provides (schema optional, include_views default true). No parameter descriptions in the description itself.

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 lists all tables and views in a schema, with a specific verb (list) and resource (tables and views). It distinguishes from sibling tools like list_schemas or describe_table.

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?

No guidance on when to use this tool vs alternatives. The description mentions optional schema but does not indicate when not to use (e.g., if schema not specified, uses default). Sibling tools like list_schemas exist, but no comparative context.

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

sample_dataC

Sample data from a table efficiently

ParametersJSON Schema
NameRequiredDescriptionDefault
tableYesTable name
schemaNoSchema name (optional)
limitNoNumber of rows to sample (default: 100)

TDQS

C2.8/5.0
Behavior2/5

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

Without annotations, the description bears full responsibility for behavioral disclosure. It only mentions 'efficiently' which is vague, and omits details like whether it returns rows, uses random sampling, or requires any permissions.

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

Conciseness3/5

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

The description is concise in one sentence, but lacks structure and fails to front-load key details like return type or typical use case.

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?

The description is insufficient given no output schema and sibling tools. It should explain what the output is (e.g., rows of data) and how sampling works.

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%, so the baseline is 3. The description does not add any additional meaning beyond the schema's parameter descriptions.

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 states the tool samples data from a table, which is clear and specific. However, it does not distinguish from siblings like describe_table which focuses on metadata.

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?

No guidance on when to use this tool versus alternatives like execute_query or describe_table. No scenarios or exclusions provided.

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

search_objectsA

Search and explore database objects (schemas, tables, views, columns, indexes) with progressive disclosure for token efficiency. Use SQL LIKE pattern (% matches any sequence, _ matches one character) to match names. Three detail levels: 'names' (most token-efficient), 'summary' (default, key metadata), 'full' (includes comments and full type info). For column/index search, narrow with schema (and optionally table) to avoid the per-call table cap.

ParametersJSON Schema
NameRequiredDescriptionDefault
patternYesSQL LIKE pattern to match object names. Use '%' to match all, '%user%' for substring, '_d' for single-char wildcard.
object_typesNoTypes of objects to search. Defaults to all 5 types. Restricting types is faster.
detail_levelNoResponse verbosity. 'names' returns just identifiers (cheapest), 'summary' adds key metadata, 'full' includes comments and type details.summary
schemaNoRestrict search to a specific schema. Strongly recommended when searching columns or indexes.
tableNoRestrict column/index search to a specific table. Without `schema`, matches a table of that name in any schema.
limitNoMax items to return (1-1000). Total match count is reported separately in 'total_found'.

TDQS

A4.5/5.0
Behavior4/5

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

Discloses progressive disclosure levels, SQL LIKE pattern matching, and per-call table cap. As a search tool, it is read-only, and no annotations exist, so description covers key behaviors well.

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?

Three sentences with front-loaded purpose, no unnecessary words. Each sentence adds essential information.

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

Completeness5/5

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

Despite 6 parameters and no output schema, the description covers all parameters, use cases, and behavioral constraints comprehensively. No gaps identified.

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?

Schema coverage is 100%, so baseline 3. Description adds value by explaining progressive disclosure, narrowing strategies, and detail levels, exceeding schema descriptions.

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?

Clearly states verb 'Search and explore', resource 'database objects', and distinct features like progressive disclosure and SQL LIKE patterns. Distinguishes from sibling tools like list_schemas or describe_table.

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?

Provides clear guidance on narrowing column/index search with schema and table parameters to avoid a per-call cap. However, does not explicitly mention when not to use or compare to siblings.

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

Install Server
RayrunBuild, deploy, and operate MCP servers without becoming an infrastructure team.ray.runAd

TDQS

A3.7/5.0
Disambiguation5/5

Each tool has a clearly distinct purpose: analyzing columns, describing tables, executing queries, explaining plans, getting database info, table relationships, listing schemas, listing tables, sampling data, and searching objects. No overlap in functionality.

Naming Consistency5/5

All tool names follow a consistent verb_noun pattern (e.g., analyze_column, describe_table, execute_query). The naming is predictable and easy to understand.

Tool Count5/5

10 tools is well-scoped for a database connection server. It provides comprehensive functionality without being overwhelming.

Completeness5/5

The tool set covers database exploration thoroughly: schema/table/column discovery, querying, analysis, relationships, and object search. No obvious gaps for read-only database interaction.

Maintenance

ActivityActive
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

  • pg-mcp

    andre-c-andersen
    A
    license
    B
    quality
    D
    maintenance
    A lightweight Postgres MCP server for safe database exploration and query analysis, read-only by default, with multi-database support.
    4
    4
    MIT

  • 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

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/yugui923/db-connect-mcp'

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