Purpose
mcp-databricks-server is a Model Context Protocol (MCP) server used to connect to the Databricks API. It enables large language models (LLMs) to run SQL queries, list Databricks jobs, and get job status, thereby interacting with the Databricks environment through natural language.
Key capabilities
The server provides the following MCP tools:
- run_sql_query(sql: str): Executes a SQL query on a Databricks SQL warehouse.
- list_jobs(): Lists all Databricks jobs in the workspace.
- get_job_status(job_id: int): Gets the status of a specific Databricks job by ID.
- get_job_details(job_id: int): Gets detailed information for a specific Databricks job.
Usage
Requirements
Requires a Databricks workspace with: a Personal access token, a SQL warehouse endpoint, and permissions to run queries and access jobs.
Installation steps
- Clone this repository.
- Create and activate a virtual environment (recommended): python -m venv .venv source .venv/bin/activate # On Windows: .venv\Scripts\activate
- Install dependencies: pip install -r requirements.txt
- Create a .env file in the root directory containing the following variables: DATABRICKS_HOST=your-databricks-instance.cloud.databricks.com DATABRICKS_TOKEN=your-personal-access-token DATABRICKS_HTTP_PATH=/sql/1.0/warehouses/your-warehouse-id
- Test the connection (optional but recommended): python test_connection.py
Getting Databricks credentials
- Host: Your Databricks instance URL (for example, your-instance.cloud.databricks.com).
- Token: Create a personal access token in Databricks: go to User Settings (click your username in the top right), select the "Developer" tab, click "Manage" under "Access tokens", generate a new token, and save it immediately.
- HTTP Path: For your SQL warehouse: go to SQL Warehouses, select your warehouse, find the connection details, and copy the HTTP Path.
Running the server
Start the MCP server. You can use the inspector to test the MCP server.
Use cases
When used with an LLM that supports the MCP protocol, this server enables natural language interaction with the Databricks environment, for example:
- "Show all tables in the database"
- "Run a query to count the records in the customer table"
- "List all my Databricks jobs"
- "Check the status of job #123"
- "Show details for job #456"
Limitations and considerations
Troubleshooting
- Connection issues: Ensure the Databricks host is correct and does not include the https:// prefix; check that the SQL warehouse is running and accessible; verify that the personal access token has the necessary permissions; run the included test script: python test_connection.py.
Security considerations
- Your Databricks personal access token provides direct access to the workspace.
- Protect your .env file and never commit it to version control.
- Consider using only Databricks tokens with appropriately scoped permissions.
- Run this server in a secure environment.
