home / mcp / database mcp server

Database MCP Server

database-mcp

Installation

Add the following to your MCP client configuration file.

Configuration

{
  "mcpServers": {
    "emilythahuman-database-mcp": {
      "url": "https://your-worker-name.your-account.workers.dev/mcp",
      "headers": {
        "DATABASE_URL": "<secret>",
        "GITHUB_CLIENT_ID": "your_github_client_id",
        "ALLOWED_USERNAMES": "user1,user2,user3",
        "GITHUB_CLIENT_SECRET": "your_github_client_secret",
        "COOKIE_ENCRYPTION_KEY": "openssl rand -hex 32"
      }
    }
  }
}

You can run a remote MCP server that lets AI assistants securely interact with your PostgreSQL databases, including Supabase, via natural language. It creates per-user database connections, validates credentials, and exposes core database tools through simple prompts, so you can list tables, run migrations, execute SQL, and more without writing low-level queries.

How to use

To use the database MCP server with your AI assistant, you connect to the MCP endpoint and invoke the available database tools through natural language prompts. You can ask to list tables in a schema, inspect installed extensions, run migrations, apply new migrations, or execute/inspect SQL results. Remember that each user operates on their own database connection with their own credentials, and all credentials are encrypted in transit and at rest. You can enable read-only modes for queries when you want to keep operations strictly to data retrieval.

Practical usage patterns include: - Inspecting database structure: list_tables for a given schema. - Checking capabilities: list_extensions to see available extensions. - Managing migrations: list_migrations to review history and apply_migration to apply safe, tracked changes. - Running queries: query for read-only data, or execute_sql for raw statements when needed. - Verifying connectivity: use connection testing to ensure your database pool remains healthy.

If you want to configure client tools, you can provide your MCP server endpoint and use the client’s native MCP integration to pick tools by name (for example, list_tables, apply_migration, or execute_sql) in natural-language prompts.

How to install

Prerequisites: - Node.js 18+ - A Cloudflare account for Cloudflare Workers deployment (or Railway as an alternative) - A GitHub account for OAuth setup - A PostgreSQL or Supabase database

1. Clone the project and install dependencies

git clone <your-repo-url>
cdfcd database-mcp
npm install

2. Set up GitHub OAuth application

3. Configure environment variables in your Cloudflare Workers environment

# These are examples; replace with your actual values
DATABASE_URL=postgresql://user:password@host:5432/database
GITHUB_CLIENT_ID=your_github_client_id
GITHUB_CLIENT_SECRET=your_github_client_secret
COOKIE_ENCRYPTION_KEY=your_random_key
ALLOWED_USERNAMES=user1,user2,user3

4. Deploy to Cloudflare Workers

npm run deploy

Additional configuration and notes

Deployment options include Cloudflare Workers (recommended) or Railway as an alternative. The server supports per-user database pools so no two users share the same database connection.

Environment variables shown here control access and connections. They should be configured securely in your hosting environment.

Connecting clients like Claude Desktop and Cursor AI involves adding your MCP server to their configuration. For Claude Desktop you point to the MCP endpoint using a local proxy, while Cursor AI accepts a direct MCP URL. The official endpoints for the worker surface are provided through standard MCP integration flows.

Security considerations include OAuth-based authentication, a user allowlist, encrypted credentials, and read-only modes for safe querying. Ensure database access is restricted to trusted clients and that your SSL/TLS configuration is correct.

Troubleshooting and notes

Common issues may involve missing or invalid credentials, OAuth misconfigurations, or permission errors. Verify the DATABASE_URL value, GitHub OAuth client details, and the allowlist. Check network connectivity to your database and confirm SSL/TLS settings are correct.

If you encounter a timeout or pool initialization error, confirm that your database server is reachable from the hosting environment and that credentials are valid.

Available tools

list_tables

Lists all tables in specified schemas.

list_extensions

Lists all PostgreSQL extensions installed in the database.

list_migrations

Lists all migrations applied to the database (supports common migration patterns).

apply_migration

Applies a SQL migration with tracking.

execute_sql

Executes any raw SQL statement.

query

Runs read-only SQL queries (legacy tool).

Steampipe Integration

Table and plugin management tools.

GitHub Authentication

OAuth-based user authentication.

Connection Testing

Automatic database connection validation.