Databricks MCP Genie

A Model Context Protocol (MCP) server with enhanced Genie AI integration that provides seamless natural language interaction between AI assistants (like Claude Desktop, Cursor) and Databricks workspaces.

What This Does

Enables AI assistants to directly interact with your Databricks workspace:

Execute SQL queries and manage warehouses
Control clusters (create, start, stop, monitor)
Run jobs and notebooks
Ask natural language questions with Genie AI
Manage Unity Catalog (catalogs, schemas, tables)
Work with DBFS, repos, and libraries

Quick Start

For Cursor Users

Recommended Setup: No manual installation needed! Use uvx to automatically run the server.

Install uv (one-time): curl -LsSf https://astral.sh/uv/install.sh | sh
Configure Cursor MCP settings with:

   {
     "command": "uvx",
     "args": ["databricks-mcp-genie"]
   }

Add your Databricks credentials to the env section

Full details in the Cursor Setup Guide.

Automated Code Review

This project now includes automated Claude Code PR reviews! Every pull request receives:

Comprehensive code quality analysis
Security vulnerability scanning
Performance optimization suggestions
Best practices validation

PRs are automatically reviewed using GitHub Actions powered by Claude.

Prerequisites

Python 3.10 or higher
Databricks workspace with personal access token
Cursor IDE, Claude Desktop, or any MCP-compatible client

Installation

For MCP Clients (Recommended): No manual installation! Use uvx in your MCP client configuration - it automatically downloads and runs the server.

For Development: ```bash

Clone the repository

git clone https://github.com/sidart10/databrics-mcp-server.git cd databrics-mcp-server

Install with uv

uv sync ```

Configuration

Get your Databricks credentials:

Workspace URL: https://your-workspace.cloud.databricks.com
Personal Access Token: Generate from User Settings > Developer > Access Tokens

Configure MCP client:

For Cursor: See the Cursor Setup Guide for detailed instructions.

For Claude Desktop: Edit ~/.config/Claude/claude_desktop_config.json:

{
  "mcpServers": {
    "databricks": {
      "command": "uvx",
      "args": ["databricks-mcp-genie"],
      "env": {
        "DATABRICKS_HOST": "https://your-workspace.cloud.databricks.com",
        "DATABRICKS_TOKEN": "your-personal-access-token-here"
      }
    }
  }
}

Note: uvx (included with uv) automatically downloads and runs the MCP server. No manual installation needed!

Restart Claude Desktop

Verify Installation

With uvx (after configuring Cursor/Claude Desktop):

Restart your MCP client
Try: "List my Databricks clusters"
If you see results, it's working!

From source (development): ``bash uv run -m databricks_mcp.main ``

Available Features

43 MCP Tools Across 9 API Modules

Genie AI (5 tools) - Natural language data analysis

list_genie_spaces - List available Genie AI spaces
start_genie_conversation - Ask questions in natural language
send_genie_followup - Continue conversations with context
get_genie_message_status - Check message processing status
get_genie_query_results - Retrieve SQL results from Genie

Clusters API (6 tools)

list_clusters, create_cluster, get_cluster
start_cluster, terminate_cluster

SQL API (1 tool)

execute_sql - Run SQL queries with warehouse

Jobs API (9 tools)

list_jobs, create_job, delete_job, run_job
list_job_runs, get_run_status, cancel_run
run_notebook, sync_repo_and_run_notebook

Notebooks API (5 tools)

list_notebooks, export_notebook, import_notebook
delete_workspace_object, get_workspace_file_content, get_workspace_file_info

DBFS API (3 tools)

list_files, dbfs_put, dbfs_delete

Unity Catalog API (7 tools)

list_catalogs, create_catalog
list_schemas, create_schema
list_tables, create_table, get_table_lineage

Repos API (4 tools)

list_repos, create_repo, update_repo, pull_repo

Libraries API (3 tools)

install_library, uninstall_library, list_cluster_libraries

Usage Examples

Using with Claude Desktop

Once configured, you can ask Claude to interact with Databricks:

"List all my running clusters"
"Execute this SQL query: SELECT * FROM my_catalog.my_schema.my_table LIMIT 10"
"Ask Genie: What were the top products by revenue last month?"
"Create a new job to run my ETL notebook daily"

Programmatic Usage

from databricks_mcp.server import DatabricksMCPServer

# Initialize server
server = DatabricksMCPServer()

# Use via MCP protocol
server.run()

Direct API Usage

from databricks_mcp.api import clusters, genie, sql

# List clusters
clusters_list = await clusters.list_clusters()

# Ask Genie a question
response = await genie.start_conversation(
    space_id="01efc298aabd1ae9bac6128988a6eaaa",
    question="Show me revenue trends by product category"
)

# Execute SQL
results = await sql.execute_sql(
    statement="SELECT * FROM sales.orders LIMIT 100",
    warehouse_id="your-warehouse-id"
)

Project Structure

databrics-mcp-server/
├── databricks_mcp/           # Main Python package
│   ├── api/                  # API modules (clusters, sql, genie, etc.)
│   ├── core/                 # Core utilities and config
│   ├── server/               # MCP server implementation
│   └── cli/                  # CLI commands
├── tests/                    # Test suite
├── examples/                 # Usage examples
├── scripts/                  # Setup and launch scripts
├── docs/                     # Documentation
└── pyproject.toml            # Package configuration

Troubleshooting

Server Won't Start

Check logs: databricks_mcp.log

Common issues:

Invalid credentials in .mcp.json
Incorrect Python path in MCP config
Missing dependencies (run pip install -e ".[dev]")

Import Errors

# Verify all imports work
.venv/bin/python -c "from databricks_mcp.server import DatabricksMCPServer"
.venv/bin/python -c "from databricks_mcp.api import clusters, sql, genie"

Connection Issues

Verify credentials: ``bash export DATABRICKS_HOST="https://your-workspace.cloud.databricks.com" export DATABRICKS_TOKEN="your-token" .venv/bin/python -c " from databricks_mcp.api import clusters import asyncio print(asyncio.run(clusters.list_clusters())) " ``

Development

Running Tests

# All tests
.venv/bin/pytest tests/ -v

# Specific test file
.venv/bin/pytest tests/test_clusters.py -v

# With coverage
.venv/bin/pytest tests/ --cov=databricks_mcp

Code Quality

# Format code
.venv/bin/black databricks_mcp/

# Lint
.venv/bin/pylint databricks_mcp/

Adding New Tools

Add API function in databricks_mcp/api/
Register tool in databricks_mcp/server/databricks_mcp_server.py:

@self.tool(
    name="your_tool_name",
    description="What your tool does with parameters: param1 (required), param2 (optional)"
)
async def your_tool(params: Dict[str, Any]) -> List[TextContent]:
    try:
        actual_params = _unwrap_params(params)
        result = await your_api_module.your_function(actual_params)
        return [{"type": "text", "text": json.dumps(result)}]
    except Exception as e:
        logger.error(f"Error: {str(e)}")
        return [{"type": "text", "text": json.dumps({"error": str(e)})}]

Documentation

Cursor Setup Guide - One-click installation for Cursor (recommended for teams)
Deployment Summary - Package distribution overview
API Contracts - API interface documentation

Requirements

Python >=3.10
mcp[cli] >=1.2.0
httpx
databricks-sdk
pytest (dev)
black (dev)
pylint (dev)

License

MIT License - See LICENSE file for details

Acknowledgments

PyPI Package: databricks-mcp-genie Source Repository: https://github.com/sidart10/databrics-mcp-server Maintainer: Sid Original Author: Olivier Debeuf De Rijcker (databricks-mcp)

Special thanks to:

Olivier Debeuf De Rijcker for the original databricks-mcp implementation
Anthropic for Claude and the MCP protocol
Databricks for their comprehensive SDK and Genie AI
The open source community

---

Built with Claude Code - AI-assisted development tool by Anthropic

Databricks MCP Genie