Tusk

Tusk MCP is a read-only PostgreSQL MCP server designed for AI agents. It exposes schema introspection and SELECT-only query execution through the Model Context Protocol, letting your agents discover data structures and safely query data without modifying it.

How to use

Connect to the MCP server from your client or agent using the provided start commands. You will run the MCP as a local or remote process and configure your agent to use the server to inspect schemas, list tables, describe columns, and execute limit-bounded read-only queries. This setup enables agents to discover data availability and perform safe, read-only data access within your environment.

How to install

Prerequisites: you should have Node.js and a package manager installed, since the MCP uses a Node-based CLI. Ensure you have network access to your PostgreSQL database and the database is reachable with the credentials you provide.

Install or run the MCP directly without a global install by using npx, or clone and run the index if you prefer building from source.

Additional setup and usage details

Configuration options let you connect to PostgreSQL with flexible authentication methods, enable SSL when needed, and optionally route connections through an SSH tunnel. There is also a structure-only mode that exposes schema information without allowing query execution.

Tools exposed by the MCP include commands to list schemas, list tables, describe a table’s columns and keys, and execute read-only queries with a safety limit.

Configuration and security

You can provide connection details directly as flags, via a connection string, or through environment variables. Passwords can be supplied from a file or via a password command. SSL can be enabled by providing CA certificates and client certificates/keys for mutual TLS.

If you want to securely access a private database, you can tunnel the connection through SSH. There is also a mode to expose only the structure so agents can discover schemas without performing queries.

Examples of integration with MCP clients

{
  "mcpServers": {
    "tusk": {
      "command": "npx",
      "args": ["-y", "tusk-mcp", "--host", "localhost", "--database", "mydb"]
    }
  }
}

Tools

The MCP provides the following read-only tools to interact with PostgreSQL data sources.

• list-schemas: List non-system schemas.

• list-tables: Tables and views with estimated row counts (partitions filtered out).

• describe-table: Columns, types, primary keys, foreign keys, and enum values inline.

• execute-query: Read-only SQL with a limit (disabled in structure-only mode).

All flags

| Flag | Type | Default | Description |
|---|---|---|---|
| `--host` | string | localhost | PostgreSQL host |
| `--port` | number | 5432 | PostgreSQL port |
| `--user` | string | — | Database user |
| `--password` | string | — | Database password |
| `--password-file` | string | — | Read password from file |
| `--password-cmd` | string | — | Run command for password |
| `--database` | string | — | Database name |
| `--connection-string` | string | — | Full connection URL |
| `--ssl-ca` | string | — | CA certificate path (enables SSL) |
| `--ssl-cert` | string | — | Client certificate path (enables SSL) |
| `--ssl-key` | string | — | Client key path (enables SSL) |
| `--ssh-host` | string | — | SSH tunnel host |
| `--ssh-port` | number | 22 | SSH tunnel port |
| `--ssh-user` | string | — | SSH username |
| `--ssh-key` | string | — | SSH private key path |
| `--ssh-password` | string | — | SSH password |
| `--structure-only` | boolean | false | Disable execute-query |

All environment variables

You can supply connection details using environment variables. Example usage includes setting the PostgreSQL host and database name.

Available tools

list-schemas

List non-system schemas available in the connected database.

list-tables

Provide a list of tables and views with estimated row counts, excluding partitions.

describe-table

Describe a table's columns, data types, primary keys, foreign keys, and inline enum values.

execute-query

Run a read-only SQL query with a safety limit; this tool is disabled when structure-only mode is active.