orcaq-mcp is a Model Context Protocol (MCP) server that gives AI agents full access to PostgreSQL databases — schema introspection, query execution, performance analysis, and database management, all through a standardized tool interface.

Built by the OrcaQ team. Full TypeScript. Zero config friction.

Features

• 22 powerful tools for complete database interaction
• Schema introspection — tables, views, functions, columns, foreign keys, indexes
• Query execution — safe read-only queries + confirmed mutations
• Performance analysis — EXPLAIN ANALYZE, active queries, database stats
• Database management — roles, databases, RLS policies, triggers
• Connection options — connection string, individual params, SSL, SSH tunnels
• Secure by default — read queries are separated from mutations, mutations require explicit confirmation
• Full TypeScript — exported types for programmatic use

Quick Start

Claude Desktop

Add to ~/Library/Application Support/Claude/claude_desktop_config.json:

{
  "mcpServers": {
    "orcaq": {
      "command": "npx",
      "args": ["-y", "orcaq-mcp"],
      "env": {
        "DATABASE_URL": "postgres://user:password@localhost:5432/mydb"
      }
    }
  }
}

Cursor

Add to .cursor/mcp.json:

{
  "mcpServers": {
    "orcaq": {
      "command": "npx",
      "args": ["-y", "orcaq-mcp"],
      "env": {
        "DATABASE_URL": "postgres://user:password@localhost:5432/mydb"
      }
    }
  }
}

VS Code (GitHub Copilot)

Add to .vscode/mcp.json:

{
  "servers": {
    "orcaq": {
      "command": "npx",
      "args": ["-y", "orcaq-mcp"],
      "env": {
        "DATABASE_URL": "postgres://user:password@localhost:5432/mydb"
      }
    }
  }
}

Windsurf

Add to ~/.codeium/windsurf/mcp_config.json:

{
  "mcpServers": {
    "orcaq": {
      "command": "npx",
      "args": ["-y", "orcaq-mcp"],
      "env": {
        "DATABASE_URL": "postgres://user:password@localhost:5432/mydb"
      }
    }
  }
}

Command Line

# Via connection string
npx orcaq-mcp --connection-string "postgres://user:pass@localhost:5432/mydb"

# Via environment variable
DATABASE_URL="postgres://user:pass@localhost/mydb" npx orcaq-mcp

# Via individual parameters
npx orcaq-mcp --host localhost --port 5432 --database mydb --username user --password pass

Connection Configuration

Environment Variables

| Variable | Description | Default | | --- | --- | --- | | DATABASE_URL | Full PostgreSQL connection URL | — | | PGHOST | Database host | — | | PGPORT | Database port | 5432 | | PGDATABASE | Database name | — | | PGUSER | Username | — | | PGPASSWORD | Password | — | | SSL_MODE | SSL mode: disable, require, verify-ca, verify-full | disable | | SSH_HOST | SSH tunnel host | — | | SSH_PORT | SSH tunnel port | 22 | | SSH_USERNAME | SSH username | — | | SSH_PASSWORD | SSH password | — | | SSH_PRIVATE_KEY | SSH private key (raw content) | — |

CLI Arguments

--connection-string   Full PostgreSQL connection URL
--host                Database host
--port                Database port (default: 5432)
--database            Database name
--username            Username
--password            Password
--ssl-mode            SSL mode
--help                Show help

Priority: CLI arguments > Environment variables

SSL Connection

{
  "mcpServers": {
    "orcaq": {
      "command": "npx",
      "args": ["-y", "orcaq-mcp"],
      "env": {
        "PGHOST": "db.example.com",
        "PGPORT": "5432",
        "PGDATABASE": "production",
        "PGUSER": "readonly_user",
        "PGPASSWORD": "secret",
        "SSL_MODE": "require"
      }
    }
  }
}

SSH Tunnel

{
  "mcpServers": {
    "orcaq": {
      "command": "npx",
      "args": ["-y", "orcaq-mcp"],
      "env": {
        "PGHOST": "10.0.0.5",
        "PGPORT": "5432",
        "PGDATABASE": "mydb",
        "PGUSER": "admin",
        "PGPASSWORD": "secret",
        "SSH_HOST": "bastion.example.com",
        "SSH_PORT": "22",
        "SSH_USERNAME": "ubuntu",
        "SSH_PRIVATE_KEY": "-----BEGIN OPENSSH PRIVATE KEY-----\n..."
      }
    }
  }
}

Available Tools

Connection

| Tool | Description | | --- | --- | | test_connection | Test database connectivity |

Schema Introspection

| Tool | Description | | --- | --- | | list_schemas | List all accessible schemas | | list_tables | List tables in a schema with size/row estimates | | describe_table | Get columns, types, defaults, foreign keys, comments | | get_table_indexes | Get all indexes on a table | | get_table_size | Get table, data, and index sizes | | get_table_ddl | Generate CREATE TABLE DDL | | get_table_rls | Get Row-Level Security status and policies | | get_table_triggers | List table triggers | | get_schema_metadata | Complete metadata for all schemas (tables, views, functions, columns, FKs, PKs) |

Views

| Tool | Description | | --- | --- | | list_views | List views and materialized views | | get_view_definition | Get SQL definition of a view | | get_view_columns | Get column definitions for a view |

Functions

| Tool | Description | | --- | --- | | list_functions | List functions and procedures | | get_function_definition | Get full function source code |

Query Execution

| Tool | Description | | --- | --- | | execute_query | Execute read-only SQL (SELECT/WITH/EXPLAIN), max 5000 rows | | execute_mutation | Execute write SQL (INSERT/UPDATE/DELETE/CREATE/ALTER/DROP) — requires confirm: true | | explain_query | EXPLAIN ANALYZE with JSON output |

Roles & Databases

| Tool | Description | | --- | --- | | list_roles | List all database roles and users | | list_databases | List all databases with size info |

Instance Monitoring

| Tool | Description | | --- | --- | | get_active_queries | Show currently running queries | | get_database_stats | Connection count, cache hit ratio, tuple stats | | cancel_query | Cancel a running query by PID | | terminate_connection | Terminate a connection by PID — requires confirm: true |

Safety

• execute_query only allows SELECT, WITH, TABLE, VALUES, and EXPLAIN statements
• execute_mutation requires explicit confirm: true parameter — agents must ask for user approval
• terminate_connection requires explicit confirm: true
• All queries are parameterized to prevent SQL injection
• Connection pooling with automatic cleanup (5-minute idle timeout)

Programmatic Usage

import { createOrcaqMcpServer } from 'orcaq-mcp';

const { server, cleanup } = createOrcaqMcpServer({
  connectionString: 'postgres://user:pass@localhost:5432/mydb',
});

// Use with any MCP transport
import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
const transport = new StdioServerTransport();
await server.connect(transport);

// Cleanup on shutdown
process.on('SIGTERM', async () => {
  await cleanup();
  await server.close();
});

Development

# Install dependencies
npm install

# Build
npm run build

# Watch mode
npm run dev

# Type check
npm run typecheck

Requirements

• Node.js >= 18
• PostgreSQL database

License

MIT — OrcaQ