Databricks MCP Server

🤖 Databricks MCP Server Template

Host Model Context Protocol (MCP) prompts and tools on Databricks Apps, enabling AI assistants like Claude to interact with your Databricks workspace through a secure, authenticated interface.

What is this?

This template lets you create an MCP server that runs on Databricks Apps. You can:

• 📝 Add prompts as simple markdown files in the prompts/ folder
• 🛠️ Create tools as Python functions that leverage Databricks SDK
• 🔐 Authenticate securely with OAuth through Databricks Apps
• 🚀 Deploy instantly to make your MCP server accessible to Claude

Think of it as a bridge between Claude and your Databricks workspace - you define what Claude can see and do, and this server handles the rest.

How it Works

Architecture Overview

┌─────────────┐       MCP Protocol      ┌──────────────────┐        OAuth         ┌─────────────────┐
│   Claude    │ ◄─────────────────────► │  dba-mcp-proxy   │ ◄──────────────────► │ Databricks App  │
│    CLI      │     (stdio/JSON-RPC)    │ (local process)  │    (HTTPS/SSE)      │  (MCP Server)   │
└─────────────┘                         └──────────────────┘                      └─────────────────┘
                                                ▲                                           │
                                                │                                           ▼
                                                └────────── Databricks OAuth ──────► Workspace APIs

Components

1. MCP Server (server/app.py): A FastAPI app with integrated MCP server that:

   • Dynamically loads prompts from prompts/*.md files
   • Exposes Python functions as MCP tools via @mcp_server.tool decorator
   • Handles both HTTP requests and MCP protocol over Server-Sent Events

2. Prompts (prompts/): Simple markdown files where:

   • Filename = prompt name (e.g., check_system.md → check_system prompt)
   • First line with # = description
   • File content = what gets returned to Claude

3. Local Proxy (dba_mcp_proxy/): Authenticates and proxies MCP requests:

   • Handles Databricks OAuth authentication automatically
   • Translates between Claude's stdio protocol and HTTP/SSE
   • Works with both local development and deployed apps

🎬 Demo

This 10-minute video shows you how to set up and use a Databricks MCP server with Claude: https://www.youtube.com/watch?v=oKE59zgb6e0

This video demonstrates creating your own MCP server with a custom jobs interface in Claude.

Quick Start

Create Your Own MCP Server

Step 1: Use this template

Or use the GitHub CLI:

gh repo create my-mcp-server --template databricks-solutions/custom-mcp-databricks-app --private

Step 2: Clone and setup

# Clone your new repository
git clone https://github.com/YOUR-USERNAME/my-mcp-server.git
cd my-mcp-server

# Run the interactive setup
./setup.sh

This will:

• Configure Databricks authentication
• Set your MCP server name
• Install all dependencies
• Create your .env.local file

Step 3: Deploy with Claude

In Claude Code, run:

/setup-mcp

This will:

• Deploy your MCP server to Databricks Apps
• Configure the MCP integration
• Show you available prompts and tools

Then restart Claude Code to use your new MCP server.

Add to Claude CLI

After deployment, add your MCP server to Claude:

# Set your Databricks configuration
export DATABRICKS_HOST="https://your-workspace.cloud.databricks.com"
export DATABRICKS_APP_URL="https://your-app.databricksapps.com"  # Get this from ./app_status.sh
export SERVER_NAME="your-server-name"  # This comes from config.yaml (set during ./setup.sh)

# Add your MCP server to Claude (user-scoped)
claude mcp add $SERVER_NAME --scope user -- \
  uvx --refresh --from git+ssh://git@github.com/YOUR-USERNAME/your-repo.git dba-mcp-proxy \
  --databricks-host $DATABRICKS_HOST \
  --databricks-app-url $DATABRICKS_APP_URL

Local Development

# Clone and setup
git clone <your-repo>
cd <your-repo>
./setup.sh

# Start dev server
./watch.sh

# Set your configuration for local testing
export DATABRICKS_HOST="https://your-workspace.cloud.databricks.com"
export DATABRICKS_APP_URL="http://localhost:8000"  # Local dev server

# Add to Claude for local testing
claude mcp add databricks-mcp-local --scope local -- \
  uvx --refresh --from git+ssh://git@github.com/YOUR-ORG/YOUR-REPO.git dba-mcp-proxy \
  --databricks-host $DATABRICKS_HOST \
  --databricks-app-url $DATABRICKS_APP_URL

Customization Guide

This template uses FastMCP, a framework that makes it ea