Allows AI agents to discover and query ClickHouse data through OtterStax's federated SQL server using MCP tools for SQL execution, schema listing, table description, object search, and table statistics.
Allows AI agents to discover and query MariaDB data through OtterStax's federated SQL server using MCP tools for SQL execution, schema listing, table description, object search, and table statistics.
Allows AI agents to discover and query MySQL data through OtterStax's federated SQL server using MCP tools for SQL execution, schema listing, table description, object search, and table statistics.
Allows AI agents to discover and query PostgreSQL data through OtterStax's federated SQL server using MCP tools for SQL execution, schema listing, table description, object search, and table statistics.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type @ followed by the MCP server name and your instructions, e.g., "@The OtterStax MCP Server list tables in the sales database and describe the orders table"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
An MCP server for OtterStax, the federated SQL server. It lets an AI agent (Claude Code, Claude Desktop, Codex, opencode, …) discover the data behind OtterStax — MySQL/MariaDB, PostgreSQL, ClickHouse, S3 and Kafka — and query it with SQL.
The server runs locally over stdio and talks to OtterStax over its PostgreSQL wire protocol.
Variable | Default | |
|
| PostgreSQL-wire address of the OtterStax server |
OtterStax does not check credentials, so the URL needs only host and port. The server runs any SQL you send it: point it only at an OtterStax you are allowed to change.
Related MCP server: dbrex
Requires Node.js 22 or newer (Claude Desktop ships its own).
Download otterstax-mcp.mcpb and open it: Claude Desktop installs it and asks for the OtterStax URL.
Or add it to claude_desktop_config.json:
{
"mcpServers": {
"otterstax": {
"command": "npx",
"args": ["-y", "@otterstax/mcp"],
"env": { "OTTERSTAX_URL": "postgresql://localhost:8817" }
}
}
}claude mcp add otterstax -e OTTERSTAX_URL=postgresql://localhost:8817 -- npx -y @otterstax/mcpcodex mcp add otterstax --env OTTERSTAX_URL=postgresql://localhost:8817 -- npx -y @otterstax/mcpor in ~/.codex/config.toml:
[mcp_servers.otterstax]
command = "npx"
args = ["-y", "@otterstax/mcp"]
tool_timeout_sec = 600 # Codex stops a tool after 60 s by default; federated queries can take longer
[mcp_servers.otterstax.env]
OTTERSTAX_URL = "postgresql://localhost:8817"In opencode.json:
{
"$schema": "https://opencode.ai/config.json",
"mcp": {
"otterstax": {
"type": "local",
"command": ["npx", "-y", "@otterstax/mcp"],
"environment": { "OTTERSTAX_URL": "postgresql://localhost:8817" }
}
}
}Tool | What it does |
| Runs any statement. Returns |
| Runs |
| Connection aliases ( |
|
|
| Tables and views under the full names to use in SQL, e.g. |
| Columns with SQL types and nullability. |
| Finds tables or columns by LIKE pattern. |
| Row count and per-column distinct count, NULL count, MIN and MAX in one query. |
Errors come back as tool errors (isError: true) with {error, code}, where code is the SQLSTATE OtterStax sent. If OtterStax goes down, the next call reconnects on its own.
The server also gives the agent OtterStax's SQL rules (table naming, date handling, query shapes that are known to crash the engine) as MCP server instructions.
npm install
npm run build # dist/index.js, one self-contained file
npm test # unit tests
npm run test:integration # against a live OtterStax, see below
npm run build:mcpb # otterstax-mcp.mcpbIntegration tests expect the OtterStax quick start on localhost:8817:
cd otterstax/examples/quick_start && docker compose up -dThey restart the qs-otterstax container once to check reconnection.
Apache-2.0
Columns of a table with their SQL types and nullability.
Inputs: table (required).
Run any SQL statement on OtterStax (SELECT, DDL, DML, COPY, CREATE SOURCE/STREAM). Tables must be fully qualified: alias.db.table or alias.db.schema.table. Returns {columns, rows, row_count}; all values come back as text or JSON numbers.
Inputs: sql (required).
Show the plan of a statement (EXPLAIN ). The OtterStax build you talk to may not support EXPLAIN yet; then this returns the server's error.
Inputs: sql (required).
List OtterStax databases. kind 'connection' is a registered backend (MySQL/PostgreSQL/ClickHouse) whose tables are named .. or ...; kind 'local' is an engine database.
Inputs: no named parameters.
List the schemas inside a database: '' for a MySQL/ClickHouse connection, '.' for a PostgreSQL one. A local database has none.
Inputs: database (required).
List tables and views under the full SQL names to use in execute_sql.
Inputs: schema, database.
Search tables or columns by name across all databases with a LIKE pattern. detail_level: names (minimal), summary (tables: column and row counts; columns: type), full (tables: also columns and indexes). summary/full on tables run COUNT(*) on each match.
Inputs: object_type (required), limit, pattern, detail_level.
Profile a table in one query: row count and, per column, distinct count, NULL count, MIN and MAX. Without columns every column is profiled, which scans the whole table on its backend.
Inputs: table (required), columns.
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
Scored across 8 tools
Each tool has a fairly clear role: discovery (list_databases/list_schemas/list_tables/describe_table), execution (execute_sql), planning (explain_query), and profiling (table_stats). However, execute_sql can already run any statement including EXPLAIN, so explain_query overlaps, and search_objects versus list_tables/describe_table have partially overlapping lookup purposes.
Seven of eight tools follow a clean verb_noun pattern (explain_query, execute_sql, list_databases, list_schemas, list_tables, describe_table, search_objects). table_stats deviates to a noun_noun form, a minor inconsistency but still readable.
Eight tools is well-scoped for a SQL database engine, covering discovery, execution, planning, and profiling without redundancy. Each tool earns its place.
The surface covers exploration (databases, schemas, tables, columns, search) plus execution, explain, and profiling, which is strong for a query engine. Minor gaps like query cancellation or session/connection management are absent but not blocking for typical agent workflows.
Query Postgres, MySQL, SQL Server, Oracle, BigQuery, ClickHouse and Redshift from your AI client.
PostgreSQL, MySQL, and SQL Server in one session. 26 read-only MCP tools for AI agents.
Safe, read-only Postgres and MySQL access for AI agents. Audit log + column-level controls.
Query 40 databases from Claude, ChatGPT, or Cursor — on any device. Read-only, encrypted, audited.
