Databricks Genie MCP Server

1 
2# Databricks Genie MCP Server
3 
4A 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.
5 
6 
7## ✨ Features
8 
9- List Genie spaces available in your Databricks workspace (Currently Manual/Using Resource)
10- Fetch metadata (title, description) of a specific Genie space
11- Start new Genie conversations with natural language questions
12- Ask follow-up questions in ongoing Genie conversations
13- Retrieve SQL and result tables in structured format
14 
15## 🧱 Prerequisites
16 
17- Python 3.7+
18- Databricks workspace with:
19  - Personal access token
20  - Genie API enabled
21  - Permissions to access Genie spaces and run queries
22 
23 
24## ⚙️ Setup
25 
261. **Clone this repository**
27 
282. **Create and activate a virtual environment** (recommended):
29  
30 
31```
32 python -m venv .venv
33 source .venv/bin/activate
34 ```
35 
36   
37**Install dependencies:**
38 
39```
40pip install -r requirements.txt
41```
42 
43Create a **.env** file in the root directory with the following variables:
44 
45```
46DATABRICKS_HOST=your-databricks-instance.cloud.databricks.com # Don't add https
47DATABRICKS_TOKEN=your-personal-access-token
48```
49 
50 
51📌 **Manually Adding Genie Space IDs**
52 
53**Note:**  
54 At this time, the Databricks Genie API **does not provide a public endpoint to list all available space IDs and titles**.  (afaik)
55As a workaround, you need to **manually add the Genie space IDs and their titles** in the `get_genie_space_id()` function in `main.py`.
56 
57 
58 
59 
60 
61## 🧪 Test the Server
62You can test the MCP server using the inspector (optional but recommended):
63 
64```
65npx @modelcontextprotocol/inspector python main.py
66```
67OR
68 
69**You can directly build and run docker to test the server**
70 
71## 💬 Use with Claude Desktop
72 
73Download Claude Desktop
74 
75**Install Your MCP Server:**
76From your project directory, run:
77 
78```
79mcp install main.py
80```
81**Once Server Installed**
82  1. Connect in Claude
83   
84   2. Open Claude Desktop
85   
86   3. Click Resources → Add Resource
87   
88   4. Select your Genie MCP Server
89   
90   5. Start chatting with your data using natural language! 🎯
91 
92 
93 
94 
95## 🧾 Obtaining Databricks Credentials
96**Host**
97Your Databricks instance URL (e.g., your-instance.cloud.databricks.com) — do not include https://
98 
99**Token**
100 
101 1. Go to your Databricks workspace
102    
103 2. Click your username (top right) → User Settings
104 3. Under the Developer tab, click Manage under "Access tokens"
105 4. Generate a new token and copy it
106 
107 
108 
109 
110## 🚀 Running the Server
111 
112```
113python main.py
114```
115This will start the Genie MCP server over the stdio transport for LLM interaction.
116 
117## 🧰 Available MCP Tools
118The following MCP tools are available:
119 
120 
121**Tool	Description**
1221. get_genie_space_id()	List available Genie space IDs and titles
1232. get_space_info(space_id: str)	Retrieve title and description of a Genie space
1243. ask_genie(space_id: str, question: str)	Start a new Genie conversation and get results
1254. follow_up(space_id: str, conversation_id: str, question: str)	Continue an existing Genie conversation
126 
127## 🛠️ Troubleshooting
128Common Issues
129- Invalid host: Ensure the host does not include https://
130 
131- Token error: Make sure your personal access token is valid and has access to Genie
132 
133- Timeout: Check if the Genie space is accessible and not idle/expired
134 
135- No data returned: Ensure your query is valid for the selected space
136 
137## 🔐 Security Considerations
138 
139 - Keep your .env file secure and never commit it to version control
140 
141 - Use minimal scope tokens with expiration whenever possible
142 
143- Avoid exposing this server in public-facing environments unless authenticated
144 
145## Claude Desktop Screenshots
146 
147![image](https://github.com/user-attachments/assets/42b391d3-0ae8-48bd-8665-a1560437b8ef)
148 
149![image](https://github.com/user-attachments/assets/eb80c99f-e854-4d55-bb0e-8a447c29ee51)
150