Databricks Genie MCP Server

What is Databricks Genie MCP Server about?

Enables LLMs to retrieve data and insights from a Databricks workspace through natural language, leveraging the Genie API for conversational query handling and structured SQL results.

How to use Databricks Genie MCP Server?

1. Clone the repository and set up a Python virtual environment.
2. Create a .env file with DATABRICKS_HOST (without https://) and DATABRICKS_TOKEN.
3. Manually add Genie space IDs in the get_genie_space_id() function (the API does not list them automatically).
4. Run the server with:

   python main.py
   

5. Test via the Model Context Protocol inspector:

   npx @modelcontextprotocol/inspector python main.py
   

6. Install the server in Claude Desktop using mcp install main.py and connect it as a resource.

Key Features of Databricks Genie MCP Server

• List available Genie spaces (manual configuration).
• Retrieve metadata (title, description) for a specific Genie space.
• Start new Genie conversations with natural language prompts.
• Ask follow‑up questions within an ongoing conversation.
• Receive SQL queries and result tables in a structured format.

Use Cases of Databricks Genie MCP Server

• Data analysts can query warehouse data conversationally without writing SQL.
• LLM‑powered assistants can fetch up‑to‑date metrics and visualizations from Databricks.
• Application developers can embed natural language data retrieval into their products.
• Business users can interact with data through Claude Desktop or other LLM interfaces.

FAQ from the Databricks Genie MCP Server

• Q: Do I need to list Genie space IDs manually? A: Yes, the current Genie API lacks an endpoint to enumerate spaces; IDs must be added in main.py.
• Q: Which environment variables are required? A: DATABRICKS_HOST (your workspace URL without https://) and DATABRICKS_TOKEN (personal access token with Genie permissions).
• Q: Can I run the server in Docker? A: Yes, build a Docker image that runs python main.py after setting the required env vars.
• Q: What if I receive a timeout or no data? A: Ensure the selected Genie space is active, the query is valid, and your token has proper scopes.
• Q: Is the server safe to expose publicly? A: Avoid exposing it without authentication; keep the .env file secure and use minimal‑scope tokens.

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

1. Clone this repository

2. 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

1. Connect in Claude

2. Open Claude Desktop

3. Click Resources → Add Resource

4. Select your Genie MCP Server

5. 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

1. Go to your Databricks workspace

2. Click your username (top right) → User Settings

3. Under the Developer tab, click Manage under "Access tokens"

4. 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

1. get_genie_space_id() List available Genie space IDs and titles
2. get_space_info(space_id: str) Retrieve title and description of a Genie space
3. ask_genie(space_id: str, question: str) Start a new Genie conversation and get results
4. 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