What is Cratedb Mcp

CrateDB MCP is a server that implements the Model Context Protocol (MCP), which standardizes the provision of context to large language models (LLMs) such as Claude, ChatGPT, and MistralAI, enabling them to interact directly with CrateDB.

Use cases

Use cases for CrateDB MCP include optimizing SQL queries, assessing cluster health, analyzing storage consumption of tables, and formatting timestamp columns, all through natural language interactions with LLMs.

How to use

To use CrateDB MCP, you need a client that supports the MCP protocol, such as Claude Desktop, ChatGPT Desktop, OpenAI agents SDK, or Cursor. Users can ask questions about their data and database state or seek help in debugging and optimizing queries.

Key features

Key features of CrateDB MCP include the ability to answer queries about data and database status, assist in query optimization, and provide accurate information by fetching data from CrateDB documentation.

Where to use

CrateDB MCP can be used in various fields where data management and analysis are crucial, such as data science, business intelligence, and application development, particularly when leveraging LLMs for enhanced data interaction.

CrateDB MCP Server

» Documentation
| Releases
| Issues
| Source code
| License
| CrateDB
| Community Forum
| Bluesky

About

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.

Introduction

The CrateDB Model Context Protocol (MCP) Server connects AI assistants directly
to your CrateDB clusters and the CrateDB knowledge base, enabling seamless
interaction through natural language.

It serves as a bridge between AI tools and your analytics database,
allowing you to analyze data, the cluster state, troubleshoot issues, and
perform operations using conversational prompts.

Experimental: Please note that the CrateDB MCP Server is an experimental
feature provided as-is without warranty or support guarantees. Enterprise
customers should use this feature at their own discretion.

Quickstart Guide

The CrateDB MCP Server is compatible with AI assistants that support the Model
Context Protocol (MCP), either using standard input/output (stdio),
server-sent events (SSE), or HTTP Streams (streamable-http).

To use the MCP server, you need a client that supports the
protocol. The most notable ones are ChatGPT, Claude, Cline Bot, Cursor,
GitHub Copilot, Mistral AI, OpenAI Agents SDK, Windsurf, and others.

The uvx launcher command is provided by the uv package manager.
The installation docs section includes guidelines on how to
install it on your machine.

Claude, Cline, Cursor, Roo Code, Windsurf

Add the following configuration to your AI assistant’s settings to enable the
CrateDB MCP Server.

• Claude: claude_desktop_config.json
• Cline: cline_mcp_settings.json
• Cursor: ~/.cursor/mcp.json or .cursor/mcp.json
• Roo Code: mcp_settings.json or .roo/mcp.json
• Windsurf: ~/.codeium/windsurf/mcp_config.json

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

VS Code

Add an MCP server to your VS Code user settings to enable the MCP server
across all workspaces in your settings.json file.

{
  "mcp": {
    "servers": {
      "cratedb-mcp": {
        "command": "uvx",
        "args": [
          "cratedb-mcp",
          "serve"
        ],
        "env": {
          "CRATEDB_CLUSTER_URL": "http://localhost:4200/",
          "CRATEDB_MCP_TRANSPORT": "stdio"
        }
      }
    }
  },
  "chat.mcp.enabled": true
}

Add an MCP server to your VS Code workspace to configure an MCP server for a
specific workspace per .vscode/mcp.json file. In this case, omit the
top-level mcp element, and start from servers instead.

Alternatively, VS Code can automatically detect and reuse MCP servers that
you defined in other tools, such as Claude Desktop.
See also Automatic discovery of MCP servers.

{
  "chat.mcp.discovery.enabled": true
}

Goose

Configure extensions in your ~/.config/goose/config.yaml.
See also using Goose extensions.

extensions:
  cratedb-mcp:
    name: CrateDB MCP
    type: stdio
    cmd: uvx
    args:
      - cratedb-mcp
      - serve
    enabled: true
    envs:
      CRATEDB_CLUSTER_URL: "http://localhost:4200/"
      CRATEDB_MCP_TRANSPORT: "stdio"
    timeout: 300

LibreChat

Configure mcpServers in your librechat.yaml.
See also LibreChat and MCP and LibreChat MCP examples.

mcpServers:
  cratedb-mcp:
    type: stdio
    command: uvx
    args:
      - cratedb-mcp
      - serve
    env:
      CRATEDB_CLUSTER_URL: "http://localhost:4200/"
      CRATEDB_MCP_TRANSPORT: "stdio"

Handbook

This section includes detailed information about how to configure and
operate the CrateDB MCP Server, and to learn about the MCP tools it
provides.

Tools are a powerful primitive in the Model Context Protocol (MCP) that enable
servers to expose executable functionality to clients. Through tools, LLMs can
interact with external systems, perform computations, and take actions in the
real world.

What’s inside

The CrateDB MCP Server provides two families of tools.

The Text-to-SQL tools talk to a CrateDB database cluster to inquire database
and table metadata, and table content.


Tool names are: get_health, get_table_metadata, query_sql

The documentation server tools looks up guidelines specific to CrateDB topics,
to provide the most accurate information possible.
Relevant information is pulled from https://cratedb.com/docs, curated per
cratedb-outline.yaml through the cratedb-about package.


Tool names are: get_cratedb_documentation_index, fetch_cratedb_docs

Install

The configuration snippets for AI assistants are using the uvx launcher
of the uv package manager to start the application after installing it,
like the npx launcher is doing it for JavaScript and TypeScript applications.
This section uses uv tool install to install the application persistently.

uv tool install --upgrade cratedb-mcp

Notes:

• We recommend using the uv package manager to install the cratedb-mcp
  package, like many other MCP servers are doing it.

  {apt,brew,pipx,zypper} install uv
  

• We recommend using uv tool install to install the program “user”-wide
  into your environment so you can invoke it from anywhere across your terminal
  sessions or MCP client programs / AI assistants.
• If you are unable to use uv tool install, you can use uvx cratedb-mcp
  to acquire the package and run the application ephemerally.

Configure

Configure the CRATEDB_CLUSTER_URL environment variable to match your CrateDB instance.
For example, when connecting to CrateDB Cloud, use a value like
https://admin:[email protected]:4200/.
When connecting to CrateDB on localhost, use http://localhost:4200/.

export CRATEDB_CLUSTER_URL="https://example.aks1.westeurope.azure.cratedb.net:4200"

export CRATEDB_CLUSTER_URL="http://localhost:4200/"

The CRATEDB_MCP_HTTP_TIMEOUT environment variable (default: 30.0) defines
the timeout for HTTP requests to CrateDB and its documentation resources
in seconds.

The CRATEDB_MCP_DOCS_CACHE_TTL environment variable (default: 3600) defines
the cache lifetime for documentation resources in seconds.

Security considerations

If you want to prevent agents from modifying data, i.e., permit SELECT statements
only, it is recommended to create a read-only database user by using “GRANT DQL”.

CREATE USER "read-only" WITH (password = 'YOUR_PASSWORD');
GRANT DQL TO "read-only";

Then, include relevant access credentials in the cluster URL.

export CRATEDB_CLUSTER_URL="https://read-only:[email protected]:4200"

The MCP Server also prohibits non-SELECT statements on the application level.
All other operations will raise a PermissionError exception, unless the
CRATEDB_MCP_PERMIT_ALL_STATEMENTS environment variable is set to a
truthy value.

Operate

Start MCP server with stdio transport (default).

cratedb-mcp serve --transport=stdio

Start MCP server with sse transport.

cratedb-mcp serve --transport=sse

Start MCP server with streamable-http transport.

cratedb-mcp serve --transport=streamable-http

Alternatively, use the CRATEDB_MCP_TRANSPORT environment variable instead of
the --transport option.

Use

To connect to the MCP server using any of the available MCP clients, use one
of the AI assistant applications, or refer to the programs in the examples folder.

We collected a few example questions that have been tested and validated by
the team, so you may also want to try them to get started. Please remember
that LLMs can still hallucinate and give incorrect answers.

• Optimize this query: “SELECT * FROM movies WHERE release_date > ‘2012-12-1’ AND revenue”
• Tell me about the health of the cluster
• What is the storage consumption of my tables, give it in a graph.
• How can I format a timestamp column to ‘2019 Jan 21’?

Please also explore the example questions from another shared collection.

Project information

Acknowledgements

Kudos to the authors of all the many software components and technologies
this project is building upon.

Contributing

The cratedb-mcp package is an open-source project, and is managed on
GitHub. Contributions of any kind are welcome and appreciated.
To learn how to set up a development sandbox, please refer to the
development documentation.

Status

The software is in the alpha stage, so breaking changes may happen.
Version pinning is strongly recommended, especially if you use it as a library.