Databricks MCP Server

How to use

You will run both a remote MCP server and a local development proxy that together enable Claude to discover and execute the prompts and tools you provide. Your prompts come from markdown files, and tools are Python functions decorated to be MCP endpoints. When you deploy, Claude can connect to your Databricks MCP server through the Databricks Apps gateway using secure OAuth.

How to install

Prerequisites you need on your machine before starting: Python and a modern runtime, and the Databricks CLI configured for authentication. You should also have Git installed to clone repositories and a shell to run setup scripts.

Step 1. Create or clone your MCP server project.

Step 2. Run the interactive setup to configure authentication, install dependencies, and generate configuration files.

Step 3. Start the local development server and prepare for deployment to Databricks Apps.

Step 4. Deploy and connect Claude to your deployed MCP server using the provided deployment commands and environment configuration.

# Example end-to-end flow (illustrative commands shown in the source content)
# Step 1: Setup a new MCP server repository from the template
gh repo create my-mcp-server --template databricks-solutions/custom-mcp-databricks-app --private

# Step 2: Clone and install dependencies, then set up configuration
git clone https://github.com/YOUR-USERNAME/my-mcp-server.git
cd my-mcp-server
./setup.sh

# Step 3: Start local development server (dev watch mode)
./watch.sh

# Step 4: Deploy to Databricks Apps and obtain the app URL
./deploy.sh
./app_status.sh
# Your deployed URL will look like: https://your-app.databricksapps.com/mcp/

# Step 5: Add MCP server to Claude once deployed
export DATABRICKS_HOST="https://your-workspace.cloud.databricks.com"
export DATABRICKS_APP_URL="https://your-app.databricksapps.com"
export SERVER_NAME="your-server-name"
claude mcp add $SERVER_NAME --scope user -- \
  uvx --refresh --from git+ssh://[email protected]/YOUR-USERNAME/your-repo.git dba-mcp-proxy \
  --databricks-host $DATABRICKS_HOST \
  --databricks-app-url $DATABRICKS_APP_URL
"}]},{

Additional sections

Configuration and security considerations are essential as you expose an MCP server to Claude. Use OAuth for secure authentication via the Databricks Apps gateway, and ensure your workspace permissions align with the prompts and tools you expose. Maintain a minimal set of prompts and tools to reduce surface area and simplify auditing.

Examples of available prompts and tools are defined in the project structure. Prompts are stored as Markdown files in the prompts/ directory, and tools are Python functions decorated to register with the MCP server. The deployment process publishes your MCP server to a Databricks App URL, after which Claude can connect and start using the defined prompts and tools.

Troubleshooting common issues includes refreshing credentials if authentication errors occur, verifying that the MCP app is deployed and reachable, and consulting logs for the deployed app if tool errors appear. If you need to re-run tests or inspect the MCP server behavior, use the provided testing scripts and the MCP Inspector interfaces described in the deployment notes.

Configuration and endpoints

Connection methods available to Claude include both a remote HTTP MCP endpoint and a local stdio proxy. Use the details shown below to configure Claude’s MCP client.

{
  "mcpServers": [
    {
      "type": "http",
      "name": "databricks_mcp",
      "url": "https://your-app.databricksapps.com/mcp",
      "args": []
    },
    {
      "type": "stdio",
      "name": "databricks_mcp_local",
      "command": "./watch.sh",
      "args": []
    }
  ],
  "envVars": [
    {"name": "DATABRICKS_HOST", "description": "Databricks workspace host URL", "required": true, "example": "https://your-workspace.cloud.databricks.com"},
    {"name": "DATABRICKS_TOKEN", "description": "Databricks access token for authentication", "required": true, "example": "YOUR_TOKEN"},
    {"name": "DATABRICKS_SQL_WAREHOUSE_ID", "description": "Default SQL warehouse for queries", "required": false, "example": "warehouse-id"}
  ]
}
```"}]},{

list_clusters

List Databricks clusters by status, returning a JSON object with cluster IDs, names, and states.

create_job

Create a Databricks job with a specified name, notebook path, and cluster, returning the job ID and a run URL.