Overview

Databricks Genie MCP Server provides a lightweight HTTP service that lets large language models (LLMs) interact with Databricks Genie using natural language. The server implements the Model Context Protocol (MCP) pattern to expose a set of tools (SQL runner, query interface, conversational agent) that an LLM can call to retrieve data, execute SQL, and maintain a multi-turn dialogue about query results.

For developers, this server bridges the gap between conversational AI and Databricks analytics. Instead of embedding database credentials or hand-coding query logic into prompts, you run a locally hosted MCP server that presents safe, structured tool interfaces the LLM can invoke. This enables programmatic, auditable execution of queries and a more robust conversational data experience.

Features

MCP-compatible HTTP service for integrating LLMs with Databricks Genie
Natural language-to-SQL translation and execution pipeline
Conversational context management for multi-turn interactions
Tool manifests that expose safe, structured operations to LLMs
Minimal installation footprint; usable locally or in a containerized environment
Supports running raw SQL and returning result summaries or full tables

Installation / Configuration

Clone the repository, install dependencies, configure credentials, and run the server. The examples below use typical Python tooling; adjust if you use a different runtime.

Clone the repo:

git clone https://github.com/yashshingvi/databricks-genie-MCP.git
cd databricks-genie-MCP

Install dependencies (pip example):

python -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt

Configure environment variables (example .env):

# .env
DATABRICKS_HOST=https://<your-databricks-instance>
DATABRICKS_TOKEN=<your-personal-access-token>
MCP_HOST=0.0.0.0
MCP_PORT=8080
LOG_LEVEL=info

Load the env file or export variables in your shell:

export DATABRICKS_HOST="https://<your-databricks-instance>"
export DATABRICKS_TOKEN="<your-token>"
export MCP_PORT=8080

Start the server (typical FastAPI/uvicorn command):

uvicorn main:app --host 0.0.0.0 --port ${MCP_PORT:-8080} --reload

Optional: run in Docker if a Dockerfile is provided:

docker build -t databricks-genie-mcp .
docker run -p 8080:8080 --env-file .env databricks-genie-mcp

Available Tools

The server exposes a set of MCP-style tools the LLM can call. Below is a representative list (tool names and behavior may vary slightly in the repository):

Tool name	Purpose	Input	Output
query_genie	Translate NL questions to SQL and run against Genie	natural language prompt, optional schema/context	concise answer, generated SQL, sample rows
run_sql	Execute a provided SQL statement	SQL string, optional limit	query results (rows), schema, execution metadata
conv_agent	Manage conversational state and follow-ups	user message, session id	agent reply, suggested next actions

Example tool manifest (conceptual JSON):

{
  "name": "run_sql",
  "description": "Execute SQL on Databricks Genie and return results",
  "inputs": {"sql": "string", "limit": "integer"},
  "outputs": {"rows": "array", "schema": "object"}
}

Example curl request to call a tool (replace host/port and payload as required):

curl -X POST "http://localhost:8080/mcp/call" \
  -H "Content-Type: application/json" \
  -d '{"tool":"run_sql","input":{"sql":"SELECT count(*) FROM sales","limit":10}}'

Use Cases

Ad-hoc data exploration: Analysts can ask questions like “What are the top 5 states by revenue for last quarter?” and receive a natural-language summary plus the SQL used and preview rows, enabling fast iteration.
Conversational data assistants: Integrate the MCP server with a chat UI or Slack bot so non-technical users ask business questions and get actionable answers without writing SQL.
Automated report generation: Combine the SQL runner with templating to generate periodic reports where an LLM composes narrative insights and the server supplies the underlying query results.
Data-science iteration: Data scientists can use the conversational agent to refine queries, ask for different aggregations, or request additional context (joins, filters) while preserving an auditable trail of executed SQL.

Tips and Best Practices

Limit privileges: Provide the Databricks token with least-privilege access necessary for operations executed via the server.
Rate limits and safety: Configure query timeouts and result-size limits to prevent expensive or runaway queries.
Session management: Use session IDs for multi-turn conversations so the conv_agent tool can maintain context and history.
Logging & auditing: Enable request and SQL logging to keep an auditable execution record for compliance and debugging.

For complete usage examples, configuration options, and the exact API contract, refer to the repository (GitHub: https://github.com

Databricks Genie MCP Server for Natural Language Queries