CrateDB Model Context Protocol Server (AI Connector)

[![Status][badge-status]][project-pypi] [![CI][badge-ci]][project-ci] [![Coverage][badge-coverage]][project-coverage] [![Downloads per month][badge-downloads-per-month]][project-downloads]

[![License][badge-license]][project-license] [![Release Notes][badge-release-notes]][project-release-notes] [![PyPI Version][badge-package-version]][project-pypi] [![Python Versions][badge-python-versions]][project-pypi]

Abstract

This CrateDB MCP Server implementation serves as a specialized bridge for natural-language interfacing with CrateDB analytical database clusters, supporting both dynamic Text-to-SQL execution and integrated documentation lookups.

The Model Context Protocol (MCP) is the standardization layer allowing AI assistants to securely and contextually interact with external services.

Nexus Introduction

The CrateDB MCP Adapter establishes a direct communication conduit between sophisticated AI agents and your CrateDB deployments, alongside its comprehensive technical documentation repositories. This allows for dynamic data analysis, real-time cluster status checks, troubleshooting assistance, and operational task execution driven purely by conversational input.

Disclaimer: This server component is currently experimental and provided without formal support assurances or warranties. Enterprise utilization requires careful internal review.

Rapid Deployment Instructions

The Adapter is engineered to integrate seamlessly with any AI client supporting the Model Context Protocol across stdio, Server-Sent Events (sse), or HTTP Streaming (http).

Integration requires a compatible client, such as ChatGPT, Claude, Cline Bot, Cursor, GitHub Copilot, Mistral AI, OpenAI Agents SDK, Windsurf, and others, leveraging the [MCP Client ecosystem]. Installation typically utilizes the uv package manager's uvx launcher.

Detailed setup procedures for common interfaces are provided below.

Configuration Snippets for Leading AI Environments

Claude, Cursor, Cline, Roo Code, Windsurf Integrations

Configure your respective AI application settings using the following structure, pointing to the service execution:

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-ai-connector": { "command": "uvx", "args": ["cratedb-mcp", "serve"], "env": { "CRATEDB_CLUSTER_URL": "http://localhost:4200/", "CRATEDB_MCP_TRANSPORT": "stdio" }, "alwaysAllow": [ "query_sql", "get_table_columns", "get_table_metadata", "get_cratedb_documentation_index", "fetch_cratedb_docs", "get_cluster_health" ], "disabled": false } } }

VS Code Integration

To embed this functionality across all workspaces, modify your global settings.json:

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

For workspace-specific setups, omit the top mcp object and start directly with servers in .vscode/mcp.json. VS Code can also auto-discover definitions from other configured tools.

Core Tool Capabilities

The Adapter exposes callable functionalities, or "Tools," allowing LLMs to execute specific actions against the CrateDB environment.

Data Interaction Tools (Text-to-SQL Family): Interact with the database schema and content. * query_sql: Executes SQL queries against the database. * get_table_columns: Retrieves column definitions for a specified table. * get_table_metadata: Fetches structural information about tables.

Knowledge Retrieval Tools: Access curated CrateDB technical documentation, indexed via the cratedb-about package from official sources (https://cratedb.com/docs). * get_cratedb_documentation_index: Fetches the index structure for documentation search. * fetch_cratedb_docs: Retrieves specific documentation segments.

Operational Tool: * get_cluster_health: Reports on the current operational status of the cluster.

Installation via Package Manager

Installation is best achieved using the uv package manager's persistent tool installation command:

shell uv tool install --upgrade cratedb-mcp

Note: If uv is unavailable, use uvx cratedb-mcp for ephemeral execution, similar to npx.

Containerized Deployment (OCI)

OCI images are hosted on GHCR. Standard image: ghcr.io/crate/cratedb-mcp:latest.

For Open WebUI compatibility, a specialized MCPO wrapper image is provided: ghcr.io/crate/cratedb-mcpo.

Example: Running via Docker (Connecting to a remote cluster)

{ "mcpServers": { "cratedb-ai-connector": { "command": "docker", "args": [ "run", "--rm", "-i", "-e", "CRATEDB_CLUSTER_URL", "ghcr.io/crate/cratedb-mcp:latest" ], "env": { "CRATEDB_CLUSTER_URL": "http://cratedb.example.org:4200/", "CRATEDB_MCP_TRANSPORT": "stdio" } } } }

Connection Parameters

Ensure CRATEDB_CLUSTER_URL points correctly to your CrateDB endpoint. For secure cloud instances, use the format provided by your CrateDB Cloud instance. For local setups, http://localhost:4200/ is typical.

Timeouts for external communications are controlled by: * CRATEDB_MCP_HTTP_TIMEOUT (Default: 30.0 seconds). * CRATEDB_MCP_DOCS_CACHE_TTL (Documentation cache expiry in seconds; Default: 3600).

Transport Configuration

Execution modes include stdio (default), sse, http, or streamable-http. Selection is made via CLI (--transport=MODE) or environment variable (CRATEDB_MCP_TRANSPORT).

HTTP-based modes require host/port configuration. Defaults are usually localhost:8000. Specific path definitions for SSE (/sse/, /messages/) and HTTP (/mcp/) can be overridden using --host, --port, and --path arguments or corresponding environment variables.

Security Hardening

To enforce read-only access (SELECT only), implement a dedicated database principal using GRANT DQL. Then, substitute the standard cluster URL with credentials tied to this restricted user:

sql CREATE USER "agent_reader" WITH (password = 'SECURE_PASS'); GRANT DQL TO "agent_reader";

This principle is enforced at the application layer; non-SELECT statements will fail with a PermissionError unless CRATEDB_MCP_PERMIT_ALL_STATEMENTS is explicitly enabled.

Prompt Customization

System instruction sets can be fine-tuned via command-line flags or environment variables.

To append default instructions, use --conventions="custom_rules.md" (or CRATEDB_MCP_CONVENTIONS).
To completely substitute default instructions, use --instructions="new_baseline.md" (or CRATEDB_MCP_INSTRUCTIONS).

Retrieve the current default prompt template for modification using: shell cratedb-mcp show-prompt > customized_instructions.md

Fragments support HTTP/S URLs, local file paths, standard input (-), or literal strings, with Markdown being the preferred formatting language.

Example Interactions

When connected via a client, agents can execute tasks such as:

Query Optimization: "Refactor this query for efficiency: \"SELECT * FROM sales WHERE transaction_value > 1000 AND region = 'EMEA'\""
System Health Check: "Provide a summary of node health and resource utilization."
Data Formatting Request: "Generate a visualization of monthly metric X trends for Q4."
Schema Inquiry: "How do I correctly output the 'event_time' column as a human-readable date string like '2024-Mar-15'?"

Development and Status

This package is open-source and maintained on GitHub. Development setup instructions are detailed in the [CONTRIBUTING_GUIDE].

Current Status: The component is in active development (alpha stage). Expect potential API shifts; version locking is advised for library consumers.