Connect Databricks Genie to LLMs
Connects LLMs to Databricks Genie for natural-language data conversations, running SQL and returning structured results over multi-turn chats.
Maintainer of this project? Claim this page to edit the listing.
1.0.0Add to Favorites
Why it matters
Enable large language models to interact with your Databricks environment. Ask natural language questions, execute SQL queries, and leverage conversational agents within Databricks.
Outcomes
What it gets done
Retrieve Databricks Genie space IDs and metadata.
Initiate new conversations with Databricks Genie via natural language.
Continue existing conversations with follow-up questions.
Extract SQL queries and structured result tables.
Install
Add it to your toolbox
Run in your project directory:
curl -fsSL https://spark.entire.vc/get/vb-databricks-genie | bash Capabilities
Tools your agent gets
Get a list of available Genie space IDs and names
Get the name and description of a Genie space
Start a new conversation with Genie and get results
Continue an existing conversation with Genie
Overview
Databricks Genie MCP Server
This MCP server connects an LLM to Databricks Genie, letting it ask natural-language questions, run multi-turn conversations, and retrieve generated SQL plus structured result tables. Use it to query Databricks data conversationally through Genie. Note that Genie space IDs must currently be added manually in main.py, since the Genie API has no public space-listing endpoint yet.
What it does
Databricks Genie MCP Server connects an LLM to the Databricks Genie API, letting it ask natural-language questions, run SQL queries, and hold multi-turn conversations with a Databricks Genie space. It can fetch a Genie space's title and description, start a new conversation with a natural-language question, continue that conversation with follow-up questions, and return the underlying SQL plus result tables in structured form.
When to use - and when NOT to
Use this when you want to query Databricks data conversationally through Genie - asking questions in plain English and getting back both the generated SQL and the result table - rather than writing SQL by hand or using the Databricks UI directly. A real limitation: the Databricks Genie API currently has no public endpoint to list all available space IDs and titles, so Genie space IDs must be manually added to the get_genie_space_id() function in main.py as a workaround - this is not a fully automatic discovery flow. It requires a Databricks workspace with a personal access token, Genie API enabled, and permission to access the relevant Genie spaces.
Capabilities
get_genie_space_id()- list manually configured Genie space IDs and titlesget_space_info(space_id)- retrieve a space's title and descriptionask_genie(space_id, question)- start a new Genie conversation and get resultsfollow_up(space_id, conversation_id, question)- continue an existing Genie conversation
How to install
python -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt
Create a .env file:
DATABRICKS_HOST=your-databricks-instance.cloud.databricks.com
DATABRICKS_TOKEN=your-personal-access-token
(Host must omit https://.) Then install into Claude Desktop:
mcp install main.py
Or run directly over stdio:
python main.py
Test with the MCP Inspector: npx @modelcontextprotocol/inspector python main.py. Requires Python 3.7+ and a Databricks personal access token with Genie permissions (User Settings > Developer > Access tokens).
Troubleshooting
Common issues it documents: an invalid host error if the host value includes https://, a token error if the personal access token is invalid or lacks Genie access, timeouts if the Genie space is inaccessible, idle, or expired, and no data returned if the query is invalid for the selected space. It also recommends avoiding exposing the server in public-facing environments unless authenticated.
Who it's for
Data teams using Databricks Genie who want to query and converse with their data through an LLM interface, and who are comfortable manually registering Genie space IDs until Databricks exposes a public space-listing endpoint. Keep the .env file out of version control and use minimally scoped, expiring tokens.
Source README
Databricks Genie MCP Server
A Model Context Protocol (MCP) server that connects to the Databricks Genie API, allowing LLMs to ask natural language questions, run SQL queries, and interact with Databricks conversational agents.
✨ Features
- List Genie spaces available in your Databricks workspace (Currently Manual/Using Resource)
- Fetch metadata (title, description) of a specific Genie space
- Start new Genie conversations with natural language questions
- Ask follow-up questions in ongoing Genie conversations
- Retrieve SQL and result tables in structured format
🧱 Prerequisites
- Python 3.7+
- Databricks workspace with:
- Personal access token
- Genie API enabled
- Permissions to access Genie spaces and run queries
⚙️ Setup
Clone this repository
Create and activate a virtual environment (recommended):
python -m venv .venv
source .venv/bin/activate
Install dependencies:
pip install -r requirements.txt
Create a .env file in the root directory with the following variables:
DATABRICKS_HOST=your-databricks-instance.cloud.databricks.com # Don't add https
DATABRICKS_TOKEN=your-personal-access-token
📌 Manually Adding Genie Space IDs
Note:
At this time, the Databricks Genie API does not provide a public endpoint to list all available space IDs and titles. (afaik)
As a workaround, you need to manually add the Genie space IDs and their titles in the get_genie_space_id() function in main.py.
🧪 Test the Server
You can test the MCP server using the inspector (optional but recommended):
npx @modelcontextprotocol/inspector python main.py
OR
You can directly build and run docker to test the server
💬 Use with Claude Desktop
Download Claude Desktop
Install Your MCP Server:
From your project directory, run:
mcp install main.py
Once Server Installed
Connect in Claude
Open Claude Desktop
Click Resources → Add Resource
Select your Genie MCP Server
Start chatting with your data using natural language! 🎯
🧾 Obtaining Databricks Credentials
Host
Your Databricks instance URL (e.g., your-instance.cloud.databricks.com) - do not include https://
Token
Go to your Databricks workspace
Click your username (top right) → User Settings
Under the Developer tab, click Manage under "Access tokens"
Generate a new token and copy it
🚀 Running the Server
python main.py
This will start the Genie MCP server over the stdio transport for LLM interaction.
🧰 Available MCP Tools
The following MCP tools are available:
Tool Description
- get_genie_space_id() List available Genie space IDs and titles
- get_space_info(space_id: str) Retrieve title and description of a Genie space
- ask_genie(space_id: str, question: str) Start a new Genie conversation and get results
- follow_up(space_id: str, conversation_id: str, question: str) Continue an existing Genie conversation
🛠️ Troubleshooting
Common Issues
Invalid host: Ensure the host does not include https://
Token error: Make sure your personal access token is valid and has access to Genie
Timeout: Check if the Genie space is accessible and not idle/expired
No data returned: Ensure your query is valid for the selected space
🔐 Security Considerations
Keep your .env file secure and never commit it to version control
Use minimal scope tokens with expiration whenever possible
Avoid exposing this server in public-facing environments unless authenticated
Claude Desktop Screenshots
FAQ
Common questions
Discussion
Questions & comments · 0
Sign In Sign in to leave a comment.