---
title: "CrateDB MCP Server: review, setup & limitations · Undominated.ai"
canonical: https://undominated.ai/mcp-servers/cratedb/
description: "Python MCP server from the crate organisation that runs SQL against a CrateDB cluster over its HTTP endpoint behind a SELECT-only check, reads table columns, table metadata and cluster health, lists a curated CrateDB documentation index, and fetches documentation pages by link under three permitted URL prefixes."
---

# CrateDB MCP Server: review, setup & limitations · Undominated.ai

> Python MCP server from the crate organisation that runs SQL against a CrateDB cluster over its HTTP endpoint behind a SELECT-only check, reads table columns, table metadata and cluster health, lists a curated CrateDB documentation index, and fetches documentation pages by link under three permitted URL prefixes.

[← Explore all mcp servers](/mcp-servers/)

ANALYTICS DATABASES / CrateDB engineering

# CrateDB MCP Server

Python MCP server from the crate organisation that runs SQL against a CrateDB cluster over its HTTP endpoint behind a SELECT-only check, reads table columns, table metadata and cluster health, lists a curated CrateDB documentation index, and fetches documentation pages by link under three permitted URL prefixes.

 [See setup guidance ↓](#setup)[Original source ↗](https://github.com/crate/cratedb-mcp)

SOURCE REVIEW

 Reviewed 2026-10-22
 Evidence 14 linked sources
 Publisher CrateDB engineering
 Licence [Apache-2.0 ↗](https://github.com/crate/cratedb-mcp/blob/4e52d26e3bb6f3fe5fa1b597b4de4d1853bd6d1c/LICENSE)
 Revision 4e52d26e3bb6
 [Read what was—and wasn’t—checked ↓](#review)

“The CrateDB MCP Server for natural-language Text-to-SQL and documentation retrieval specializes in CrateDB database clusters. The Model Context Protocol (MCP) is a protocol that standardizes providing context to language models and AI assistants.”

 [CrateDB engineering · upstream description ↗](https://github.com/crate/cratedb-mcp/blob/4e52d26e3bb6f3fe5fa1b597b4de4d1853bd6d1c/README.md) Our analysis follows below.

01 / THE REASONING

## Why this made the selection.

 - The crate organisation publishes it in crate/cratedb-mcp; pyproject.toml names the package cratedb-mcp, the author CrateDB engineering, the licence Apache-2.0, requires Python >=3.10, classifies it Development Status :: 4 - Beta, and installs the script cratedb-mcp.
- core.py registers six tools: query_sql, get_table_columns and get_table_metadata for Text-to-SQL, get_cratedb_documentation_index and fetch_cratedb_docs for documentation, and get_cluster_health. tool.py sends every query to the cluster's /_sql endpoint.
- query_sql runs a statement only when util/sql.py classifies it as one SELECT with no INTO keyword, unless CRATEDB_MCP_PERMIT_ALL_STATEMENTS is set to a truthy value, and the configuration page recommends a read-only database user created with GRANT DQL in addition.

### A good fit for

 - Answer a question about CrateDB data by letting the assistant read table columns and run a SELECT against the cluster.
- Check CrateDB cluster health from sys.health and per-table metadata such as shards, replicas and record counts.
- Look up CrateDB SQL syntax or guidance from the curated documentation index and fetch the page text.
- Serve the tools over SSE or HTTP on a chosen host, port and path instead of stdio.

### Weigh up before choosing

 - The pinned commit 4e52d26e3bb6f3fe5fa1b597b4de4d1853bd6d1c is the default-branch head read on 2026-10-22 and is dated 2026-08-18. pyproject.toml classifies the package as Development Status :: 4 - Beta.
- The README says "The software is in the beta stage, so breaking changes may happen" and that version pinning is strongly recommended.
- The SELECT check is a sqlparse classification: the first statement's type must be SELECT, no token may be the keyword INTO, and the text must parse as one statement. util/sql.py marks it "FIXME: Revisit implementation, it might be too naive or weak" with issue 10. A truthy CRATEDB_MCP_PERMIT_ALL_STATEMENTS skips it, and settings.py then warns that the agent "can write and modify the connected database".
- get_table_metadata and get_cluster_health send fixed query constants straight to /_sql without the SELECT check; query_sql and get_table_columns go through it.
- The cluster credentials travel inside CRATEDB_CLUSTER_URL as user:password, as the configuration page shows; the default URL is http://localhost:4200.
- fetch_cratedb_docs accepts a link that starts with https://cratedb.com/, https://github.com/crate or https://raw.githubusercontent.com/crate. The two GitHub prefixes have no trailing slash, so they also match any owner whose name begins with "crate".
- Over SSE or HTTP, cli.py passes only host, port and path to the server; the files read configure no client authentication for those transports. The host defaults to 127.0.0.1, and the configuration page shows CRATEDB_MCP_HOST=0.0.0.0.
- The --instructions and --conventions options, or CRATEDB_MCP_INSTRUCTIONS and CRATEDB_MCP_CONVENTIONS, load prompt text from an HTTP(S) URL on any host (following up to 3 redirects), a local file, standard input or a direct string. --instructions replaces the built-in prompt, and the loaded text becomes the server's instructions to the model.
- The client JSON's alwaysAllow list names five tools and leaves out get_table_columns; it includes query_sql. The OCI snippet uses the image tag ghcr.io/crate/cratedb-mcp:latest, which pins no version.
- The LICENSE is the Apache License 2.0 text ending at "END OF TERMS AND CONDITIONS", with no copyright line. The README defines a [Releases] link to https://github.com/surister/cratedb-mcp/releases (line 49) that it never uses; its Release Notes badge points to crate/cratedb-mcp.

02 / THE REVIEW RECORD

## What we actually inspected.

Source review has boundaries. A clear record is more useful than a “safe” badge.

### Material inspected

 - README.md at 4e52d26e3bb6f3fe5fa1b597b4de4d1853bd6d1c: About, the Releases link and Status.
- LICENSE at the same revision: Apache License 2.0 through END OF TERMS AND CONDITIONS, with no copyright appendix.
- pyproject.toml: name, description, licence, author, requires-python, Beta classifier, script.
- docs/install/package.md: the uv tool install line and the uvx alternative.
- docs/install/integrate.md: every client configuration, including the OCI snippet.
- docs/configure/index.md: cluster URL, timeouts, transports, security considerations and prompt customisation.
- cratedb_mcp/core.py: tool registration.
- cratedb_mcp/tool.py: query_cratedb, every tool function, the documentation URL check.
- cratedb_mcp/util/sql.py: sql_is_permitted and SqlStatementClassifier.
- cratedb_mcp/settings.py: CRATEDB_CLUSTER_URL, CRATEDB_MCP_HTTP_TIMEOUT, CRATEDB_MCP_PERMIT_ALL_STATEMENTS and CRATEDB_MCP_DOCS_CACHE_TTL.
- cratedb_mcp/knowledge.py: the query constants, the permitted documentation URL prefixes and the cached HTTP client.
- cratedb_mcp/cli.py: the serve options and their defaults.
- cratedb_mcp/prompt/__init__.py: how instruction and convention fragments are loaded.
- docs/backlog.md: the open item on the Hishel cache location.

### Our findings

 - Every SQL path posts to {CRATEDB_CLUSTER_URL}/_sql with httpx. Only query_sql applies sql_is_permitted, and get_table_columns calls query_sql; the metadata and health tools use fixed constants.
- cli.py lowers httpx logging to WARNING with the comment "Tame logging of HTTPX to not reveal credentials", because the cluster URL may carry them.
- The documentation tools read an outline from the cratedb-about package and fetch pages through a hishel cache client with a SQLite store; the cache lifetime comes from CRATEDB_MCP_DOCS_CACHE_TTL (default 3600 s).
- The configuration page names transports stdio, http, sse and streamable-http and says http "was called `streamable-http` in earlier spec iterations"; this record lists them as stdio, SSE and Streamable HTTP.
- The client JSON in docs/install/integrate.md is the configExample, unchanged and in source key order.

### Not established by this review

 - Not executed: it was not installed or run.
- No CrateDB cluster or documentation URL was contacted, and the SQL classifier was not run against any statement.
- The cratedb-about package that supplies the documentation outline, the OCI images, docs/install/oci.md and cratedb_mcp/prompt/instructions.md were not read.

The review applies to the material and revision named here. A newer upstream release can change its behavior.

03 / PUT IT TO WORK

## Connect a server deliberately.

[Upstream setup instructions ↗](https://github.com/crate/cratedb-mcp/blob/4e52d26e3bb6f3fe5fa1b597b4de4d1853bd6d1c/docs/install/package.md)

DOCUMENTED COMMAND

 uv tool install --upgrade cratedb-mcp Copy command ↗

Copying does not execute this command. It may retrieve a newer version than the reviewed source.

 - docs/install/package.md prints `uv tool install --upgrade cratedb-mcp` to install the program user-wide; it pins no version, and the README recommends pinning one.
- The same page says that without `uv tool install`, `uvx cratedb-mcp` acquires the package and runs it ephemerally, and gives `{apt,brew,pipx,zypper} install uv` for uv itself.
- Add a client block from docs/install/integrate.md, which starts `uvx` with `["cratedb-mcp", "serve"]` and sets CRATEDB_CLUSTER_URL and CRATEDB_MCP_TRANSPORT.

### Before you start

 - uv, as docs/install/package.md recommends.
- Python 3.10 or later.
- A CrateDB cluster URL, with credentials for a read-only user as the configuration page recommends.

### Documented configuration example

Use the client and authentication context described in the setup guidance. Configuration formats vary between hosts.

 {
 "mcpServers": {
 "cratedb-mcp": {
 "command": "uvx",
 "args": [
 "cratedb-mcp",
 "serve"
 ],
 "env": {
 "CRATEDB_CLUSTER_URL": "http://localhost:4200/",
 "CRATEDB_MCP_TRANSPORT": "stdio"
 },
 "alwaysAllow": [
 "get_cluster_health",
 "get_table_metadata",
 "query_sql",
 "get_cratedb_documentation_index",
 "fetch_cratedb_docs"
 ],
 "disabled": false
 }
 }
} Copy configuration ↗

### Compatibility

Python 3.10 or later, as pyproject.toml states. · A CrateDB cluster reachable over HTTP, local or CrateDB Cloud, as the configuration page shows. · Clients with printed configurations in docs/install/integrate.md: Claude, Cline, Cursor, Roo Code, Windsurf, VS Code, Goose and LibreChat, plus a Docker or Podman snippet.

### Implementation

Python

### Transports

stdio · SSE · Streamable HTTP

### CrateDB cluster URL with credentials

 - Reads CRATEDB_CLUSTER_URL, which carries the database user and password, and posts SQL to its /_sql endpoint with that user's rights.
- query_sql admits one SELECT statement with no INTO keyword; a truthy CRATEDB_MCP_PERMIT_ALL_STATEMENTS admits every statement, writes included.
- fetch_cratedb_docs makes HTTP GET requests to links under https://cratedb.com/, https://github.com/crate and https://raw.githubusercontent.com/crate, and caches the responses in a hishel SQLite store created when the module loads, with no path set; docs/backlog.md lists using platformdirs.user_cache_dir for Hishel as open work.
- With --transport sse, http or streamable-http it listens on the configured host and port (default 127.0.0.1:8000); no client authentication is configured in the files read.
- Loads prompt instructions or conventions from any HTTP(S) URL (up to 3 redirects), a file, standard input or a string when --instructions, --conventions or their environment variables are set.

### Cost model

Apache-2.0. The files read here do not state a fee for this server, for CrateDB or for CrateDB Cloud.

04 / FOLLOW THE EVIDENCE

## The source trail.

Our notes are separate from the original resource. Check upstream before adopting a new version.

 - [CrateDB MCP Server README at 4e52d26e ↗](https://github.com/crate/cratedb-mcp/blob/4e52d26e3bb6f3fe5fa1b597b4de4d1853bd6d1c/README.md) Checked 2026-10-22 https://github.com/crate/cratedb-mcp/blob/4e52d26e3bb6f3fe5fa1b597b4de4d1853bd6d1c/README.md Supports: upstreamDescription, install.steps, limitations[1], limitations[9]
- [Apache License 2.0 at 4e52d26e ↗](https://github.com/crate/cratedb-mcp/blob/4e52d26e3bb6f3fe5fa1b597b4de4d1853bd6d1c/LICENSE) Checked 2026-10-22 https://github.com/crate/cratedb-mcp/blob/4e52d26e3bb6f3fe5fa1b597b4de4d1853bd6d1c/LICENSE Supports: license, limitations[9]
- [pyproject.toml at 4e52d26e ↗](https://github.com/crate/cratedb-mcp/blob/4e52d26e3bb6f3fe5fa1b597b4de4d1853bd6d1c/pyproject.toml) Checked 2026-10-22 https://github.com/crate/cratedb-mcp/blob/4e52d26e3bb6f3fe5fa1b597b4de4d1853bd6d1c/pyproject.toml Supports: publisher, whySelected, language, compatibility, limitations[0]
- [docs/install/package.md at 4e52d26e ↗](https://github.com/crate/cratedb-mcp/blob/4e52d26e3bb6f3fe5fa1b597b4de4d1853bd6d1c/docs/install/package.md) Checked 2026-10-22 https://github.com/crate/cratedb-mcp/blob/4e52d26e3bb6f3fe5fa1b597b4de4d1853bd6d1c/docs/install/package.md Supports: install
- [docs/install/integrate.md at 4e52d26e ↗](https://github.com/crate/cratedb-mcp/blob/4e52d26e3bb6f3fe5fa1b597b4de4d1853bd6d1c/docs/install/integrate.md) Checked 2026-10-22 https://github.com/crate/cratedb-mcp/blob/4e52d26e3bb6f3fe5fa1b597b4de4d1853bd6d1c/docs/install/integrate.md Supports: configExample, compatibility, install.steps, limitations[8], review.findings
- [docs/configure/index.md at 4e52d26e ↗](https://github.com/crate/cratedb-mcp/blob/4e52d26e3bb6f3fe5fa1b597b4de4d1853bd6d1c/docs/configure/index.md) Checked 2026-10-22 https://github.com/crate/cratedb-mcp/blob/4e52d26e3bb6f3fe5fa1b597b4de4d1853bd6d1c/docs/configure/index.md Supports: access.permissions, limitations, transports, bestFor, review.findings
- [cratedb_mcp/core.py at 4e52d26e ↗](https://github.com/crate/cratedb-mcp/blob/4e52d26e3bb6f3fe5fa1b597b4de4d1853bd6d1c/cratedb_mcp/core.py) Checked 2026-10-22 https://github.com/crate/cratedb-mcp/blob/4e52d26e3bb6f3fe5fa1b597b4de4d1853bd6d1c/cratedb_mcp/core.py Supports: summary, whySelected, limitations[7]
- [cratedb_mcp/tool.py at 4e52d26e ↗](https://github.com/crate/cratedb-mcp/blob/4e52d26e3bb6f3fe5fa1b597b4de4d1853bd6d1c/cratedb_mcp/tool.py) Checked 2026-10-22 https://github.com/crate/cratedb-mcp/blob/4e52d26e3bb6f3fe5fa1b597b4de4d1853bd6d1c/cratedb_mcp/tool.py Supports: summary, whySelected, bestFor, access.permissions, limitations, review.findings
- [cratedb_mcp/util/sql.py at 4e52d26e ↗](https://github.com/crate/cratedb-mcp/blob/4e52d26e3bb6f3fe5fa1b597b4de4d1853bd6d1c/cratedb_mcp/util/sql.py) Checked 2026-10-22 https://github.com/crate/cratedb-mcp/blob/4e52d26e3bb6f3fe5fa1b597b4de4d1853bd6d1c/cratedb_mcp/util/sql.py Supports: limitations, access.permissions, review.findings
- [cratedb_mcp/settings.py at 4e52d26e ↗](https://github.com/crate/cratedb-mcp/blob/4e52d26e3bb6f3fe5fa1b597b4de4d1853bd6d1c/cratedb_mcp/settings.py) Checked 2026-10-22 https://github.com/crate/cratedb-mcp/blob/4e52d26e3bb6f3fe5fa1b597b4de4d1853bd6d1c/cratedb_mcp/settings.py Supports: access.permissions, limitations
- [cratedb_mcp/knowledge.py at 4e52d26e ↗](https://github.com/crate/cratedb-mcp/blob/4e52d26e3bb6f3fe5fa1b597b4de4d1853bd6d1c/cratedb_mcp/knowledge.py) Checked 2026-10-22 https://github.com/crate/cratedb-mcp/blob/4e52d26e3bb6f3fe5fa1b597b4de4d1853bd6d1c/cratedb_mcp/knowledge.py Supports: access.permissions, limitations, review.findings
- [cratedb_mcp/cli.py at 4e52d26e ↗](https://github.com/crate/cratedb-mcp/blob/4e52d26e3bb6f3fe5fa1b597b4de4d1853bd6d1c/cratedb_mcp/cli.py) Checked 2026-10-22 https://github.com/crate/cratedb-mcp/blob/4e52d26e3bb6f3fe5fa1b597b4de4d1853bd6d1c/cratedb_mcp/cli.py Supports: transports, access.permissions, limitations
- [cratedb_mcp/prompt/__init__.py at 4e52d26e ↗](https://github.com/crate/cratedb-mcp/blob/4e52d26e3bb6f3fe5fa1b597b4de4d1853bd6d1c/cratedb_mcp/prompt/__init__.py) Checked 2026-10-22 https://github.com/crate/cratedb-mcp/blob/4e52d26e3bb6f3fe5fa1b597b4de4d1853bd6d1c/cratedb_mcp/prompt/__init__.py Supports: access.permissions, limitations[7]
- [docs/backlog.md at 4e52d26e ↗](https://github.com/crate/cratedb-mcp/blob/4e52d26e3bb6f3fe5fa1b597b4de4d1853bd6d1c/docs/backlog.md) Checked 2026-10-22 https://github.com/crate/cratedb-mcp/blob/4e52d26e3bb6f3fe5fa1b597b4de4d1853bd6d1c/docs/backlog.md Supports: access.permissions

KEEP COMPARING

## Other approaches to consider.

Related by category or shared topics. These are alternatives to inspect, not a measured quality order.

 [### Teradata MCP Server ↗ Explore Teradata tables, profile data and investigate workloads using selectable tool modules.](/mcp-servers/teradata/)[### ClickHouse MCP Server ↗ Queries ClickHouse and inspects table metadata, with read-only SQL by default and separate authentication for network transports.](/mcp-servers/clickhouse/)[### Firebolt MCP Server ↗ Go MCP server from Firebolt that connects a client to Firebolt Cloud or Firebolt Core, runs SQL, and exposes Firebolt documentation tools.](/mcp-servers/firebolt/)

 [AI Tools ↗](/tools/)[Skills ↗](/skills/)[Agents ↗](/agents/)[MCP Servers ↗](/mcp-servers/)[Workflows ↗](/workflows/)

## Continue your investigation

 - [Inspect resource evidence](/tools/)
- [Choose a host](/agents/)
- [Inspect reusable workflows](/skills/)
- [Use Undominated data](/api/)
