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.