使用说明

_CHMCP服务器

一个基于Docker的模型上下文协议（MCP）服务器，它通过结合copula CLI和SDK提供全面的copula集成。该服务器使AI助手能够通过一个统一的界面与copula工作区进行交互，该界面根据任务要求在CLI命令和SDK操作之间进行智能选择。

🚀 主要特点

🐳 Docker第一架构

用于一致环境的容器化部署
已预先配置了copula CLI和SDK
轻松部署到任何容器平台
独立的依赖关系和安全的执行

🔄 双模式操作

CLI工具：用于文件操作、身份验证和工作区管理的直接命令行界面
SDK工具：对复杂查询、数据操作和自动化的程序化访问
混合工具：基于操作类型在CLI和SDK之间进行智能选择

🖥️ 群集管理

列出、启动、停止和重新启动群集
获取详细的集群状态和配置
自动集群生命周期管理
实时集群监控

📝 工作区操作

创建、读取、更新和删除笔记本和文件
在copula集群上执行代码
支持Python、SQL、Scala和R笔记本
工作区文件系统导航

🗄️ Unity目录集成

浏览目录、模式和表
在SQL仓库上执行SQL查询
获取详细的表元数据和模式信息
数据沿袭和治理操作

🤖 ML和MLflow支持

列出实验和注册模型
获取模型版本和服务端点
访问工作流跟踪和模型注册表
模型部署和监控

⚡ 工作和管道管理

将笔记本作为作业创建和运行
监控作业执行并获取结果
Delta Live Tables管道运营
工作流编排

🚀 快速开始

先决条件

Python 3.11+
jms工作区访问
个人访问令牌或服务主体凭据

安装

克隆存储库：

git clone <repository-url>
cd databricks-mcp-server

创建虚拟环境：

python -m venv .venv
.venv\Scripts\activate  # Windows
# source .venv/bin/activate  # Linux/macOS

安装依赖项：
```
pip install -e .
```
配置凭据： 在MCP客户端配置中设置您的凭据（请参阅下面的用法部分）

与MCP客户端一起使用

Claude桌面配置

安装软件包后(pip install -e .)，将此添加到您的Claude Desktop MCP服务器配置中：

{
  "mcpServers": {
    "databricks": {
      "command": "databricks-mcp-server",
      "env": {
        "DATABRICKS_HOST": "https://your-workspace.cloud.databricks.com",
        "DATABRICKS_TOKEN": "your-databricks-token-here",
        "DATABRICKS_MCP_PORT": "4040",
        "DATABRICKS_MCP_HOST": "0.0.0.0"
      }
    }
  }
}

替换占位符值：

your-workspace.cloud.databricks.com → 您的实际copula工作区URL
your-databricks-token-here → 您的实际copula个人访问令牌

直接命令行使用

# After package installation
databricks-mcp-server

# Alternative
python -m databricks_mcp_server

⚙️ 配置

MCP客户端配置

服务器从MCP客户端配置中设置的环境变量中获取配置。 不需要.env文件 -所有配置都是通过MCP客户端JSON完成的。

所需的环境变量：

DATABRICKS_HOST -您的copula工作区URL
DATABRICKS_TOKEN -您的copula个人访问令牌

可选环境变量：

DATABRICKS_MCP_PORT -服务器端口（默认值：3000）
DATABRICKS_MCP_HOST -服务器主机（默认值：0.0.0.0）
DATABRICKS_MCP_LOG_LEVEL -日志级别（默认值：INFO）
DATABRICKS_CLUSTER_ID -默认执行集群
DATABRICKS_WAREHOUSE_ID -默认SQL仓库

替代身份验证（可选）：

DATABRICKS_CLIENT_ID -OAuth客户端ID
DATABRICKS_CLIENT_SECRET -OAuth客户端密钥
DATABRICKS_AZURE_TENANT_ID -Azure AD租户ID

MCP客户端配置示例

适用于Claude桌面版（Python包）

添加到您的 claude_desktop_config.json:

{
  "mcpServers": {
    "databricks": {
      "command": "docker",
      "args": [
        "run", "--rm", "-i",
        "--env-file", "/path/to/.env",
        "databricks-mcp-server:latest"
      ]
    }
  }
}

适用于带有MCP扩展的VS代码（Docker）

添加到MCP配置中：

{
  "mcpServers": {
    "databricks": {
      "command": "docker",
      "args": [
        "run", "--rm", "-i",
        "-e", "DATABRICKS_HOST=https://your-workspace.cloud.databricks.com",
        "-e", "DATABRICKS_TOKEN=your-pat-token",
        "databricks-mcp-server:latest"
      ]
    }
  }
}

用于开发（本地Python）

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

📖 使用示例

群集管理

# List all clusters (uses SDK for detailed info)
clusters = await cluster_list()

# Get cluster status (hybrid: CLI for quick status, SDK for details)
status = await cluster_get_status(cluster_id="1234-567890-abc123")

# Start a cluster (SDK for programmatic control)
result = await cluster_start(cluster_id="1234-567890-abc123", wait=True)

# Monitor cluster events (SDK streaming)
events = await cluster_get_events(cluster_id="1234-567890-abc123")

工作区操作

# List workspace files (CLI for file system operations)
files = await workspace_list(path="/Users/your-email@company.com")

# Create a new notebook (CLI for file operations)
await workspace_create_notebook(
    path="/Users/your-email@company.com/my-notebook",
    content="print('Hello, Databricks!')",
    language="PYTHON"
)

# Execute code on a cluster (SDK for execution control)
result = await cluster_execute_code(
    cluster_id="1234-567890-abc123",
    code="spark.sql('SELECT 1').show()",
    language="python"
)

# Upload files to workspace (CLI for file uploads)
await workspace_upload_file(
    local_path="./data.csv",
    workspace_path="/FileStore/shared_uploads/data.csv"
)

作业管理

# Create and run a notebook job (hybrid approach)
job_run = await job_run_notebook(
    notebook_path="/Users/your-email@company.com/my-notebook",
    cluster_id="1234-567890-abc123",
    parameters={"param1": "value1"},
    wait=True
)

# Monitor job progress (SDK for real-time updates)
status = await job_get_run_status(run_id=job_run["run_id"])

# Get job output (CLI for log retrieval)
output = await job_get_run_output(run_id=job_run["run_id"])

Unity目录

# List catalogs (SDK for metadata operations)
catalogs = await catalog_list_catalogs()

# Browse schema and tables (SDK for structured queries)
tables = await catalog_list_tables(catalog_name="main", schema_name="default")

# Execute SQL query (SDK for query execution)
result = await catalog_execute_sql(
    warehouse_id="abc123def456",
    query="SELECT COUNT(*) FROM main.default.my_table"
)

# Get table lineage (SDK for governance features)
lineage = await catalog_get_table_lineage(
    catalog_name="main",
    schema_name="default",
    table_name="my_table"
)

ML和MLflow操作

# List MLflow experiments (SDK for ML operations)
experiments = await ml_list_experiments()

# Create and log to experiment (SDK for tracking)
run = await ml_create_run(
    experiment_id="123456",
    run_name="my-experiment-run"
)

# Register model (SDK for model registry)
model = await ml_register_model(
    name="my-model",
    source="runs:/run-id/model"
)

# Deploy model to serving endpoint (SDK for deployment)
endpoint = await ml_create_serving_endpoint(
    name="my-model-endpoint",
    model_name="my-model",
    model_version="1"
)

🛠️ 可用工具

🖥️ 群集管理工具

cluster_list -列出所有集群及其详细信息（SDK）
cluster_get_status -获取实时集群状态（混合）
cluster_start -启动集群并等待就绪状态（SDK）
cluster_restart -使用可选配置更新（SDK）重新启动群集
cluster_terminate -终止集群（SDK）
cluster_get_events -获取集群事件日志（SDK）
cluster_resize -调整集群大小（添加/删除节点）（SDK）

📁 工作区管理工具

workspace_list -列出工作区中的文件和文件夹（CLI）
workspace_get_content -获取文件/笔记本内容（CLI）
workspace_create_notebook -创建新笔记本（CLI）
workspace_create_folder -创建工作区文件夹（CLI）
workspace_upload_file -将本地文件上传到工作区（CLI）
workspace_download_file -在本地下载工作区文件（CLI）
workspace_delete -删除工作区文件/文件夹（CLI）
workspace_move -移动/重命名工作区项（CLI）

🔧 代码执行工具

cluster_execute_code -在集群上交互式执行代码（SDK）
cluster_execute_notebook -在集群上执行整个笔记本（SDK）
cluster_get_execution_context -获取或创建执行上下文（SDK）
cluster_cancel_execution -取消运行代码执行（SDK）

⚡ 作业管理工具

job_list -列出工作区（SDK）中的所有作业
job_get -获取作业配置和详细信息（SDK）
job_create -创建新作业定义（SDK）
job_run_notebook -将笔记本作为一次性作业运行（SDK）
job_run_now -触发现有作业运行（SDK）
job_get_run_status -获取作业运行状态和进度（SDK）
job_get_run_output -获取作业运行日志和输出（CLI）
job_list_runs -列出最近运行的作业（SDK）
job_cancel_run -取消正在运行的作业（SDK）

🗄️ Unity目录工具

catalog_list_catalogs -列出可用目录（SDK）
catalog_list_schemas -列出目录中的架构（SDK）
catalog_list_tables -列出架构中的表（SDK）
catalog_get_table -获取表元数据和模式（SDK）
catalog_execute_sql -在仓库上执行SQL查询（SDK）
catalog_list_warehouses -列出SQL仓库（SDK）
catalog_get_table_lineage -获取数据沿袭信息（SDK）
catalog_create_table -创建新表（SDK）
catalog_grant_permissions -授予表/架构权限（CLI）

🤖 ML和MLflow工具

ml_list_experiments -列表流实验（SDK）
ml_get_experiment -获取实验详细信息并运行（SDK）
ml_create_experiment -创建新实验（SDK）
ml_create_run -创建新的实验运行（SDK）
ml_log_metrics -记录要运行的指标（SDK）
ml_log_artifacts -记录要运行的工件（SDK）
ml_list_models -列出已注册的型号（SDK）
ml_get_model -获取模型详细信息和版本（SDK）
ml_register_model -从运行中注册模型（SDK）
ml_list_model_versions -列出模型版本（SDK）
ml_list_serving_endpoints -列出服务端点的模型（SDK）
ml_create_serving_endpoint -创建服务端点（SDK）
ml_get_serving_endpoint -获取端点状态和配置（SDK）

🔍 监控和记录工具

logs_get_cluster_logs -获取群集驱动程序/执行器日志（CLI）
logs_get_job_logs -获取作业运行日志（CLI）
metrics_get_cluster_metrics -获取集群性能指标（SDK）
metrics_get_job_metrics -获取作业执行指标（SDK）

🏗️ 建筑与开发

项目结构

databricks-mcp-server/
├── README.md                    # This file
├── pyproject.toml              # Python package configuration
├── Dockerfile                  # Docker container definition
├── docker-compose.yml          # Docker Compose configuration
├── .env.example                # Environment variables template
├── .gitignore                  # Git ignore patterns
├── databricks_mcp_server/      # Main package
│   ├── __init__.py             # Package initialization
│   ├── server.py               # FastMCP server implementation
│   ├── config.py               # Configuration management
│   ├── models.py               # Pydantic data models
│   └── tools/                  # Tool implementations
│       ├── __init__.py         # Tools package init
│       └── sdk_tools.py        # Reliable Databricks SDK tools
├── tests/                      # Test suite
│   ├── __init__.py
│   ├── test_sdk_tools.py
│   └── test_integration.py
└── scripts/                    # Utility scripts
    ├── setup.sh                # Development setup
    └── test.sh                 # Test runner

工具架构

服务器实现了 基于SDK的可靠架构:

SDK工具 (sdk_tools.py)

原生Python SDK集成使用官方 databricks-sdk
最适合：所有copula操作-可靠、快速、可投入生产
优势:
- 类型安全和结构化响应
- 异步操作以获得更好的性能
- 没有CLI依赖关系或超时问题
- 具有正确错误处理的一致JSON响应
- API直接访问实时数据
用途: databricks-sdk 具有异步/等待模式和适当的错误处理

备注：由于超时问题和函数调用错误，CLI和混合工具已被删除。SDK方法提供了所有必要的功能，具有更好的可靠性。

开发设置

地方发展

# Clone repository
git clone <repository-url>
cd databricks-mcp-server

# Create virtual environment
python -m venv venv
source venv/bin/activate  # On Windows: venv\Scripts\activate

# Install in development mode
pip install -e ".[dev]"

# Set up pre-commit hooks
pre-commit install

Docker开发

# Build development image
docker build -t databricks-mcp-server:dev .

# Run with development mount
docker run -it --rm \
  -v $(pwd):/app \
  -e DATABRICKS_HOST="your-host" \
  -e DATABRICKS_TOKEN="your-token" \
  databricks-mcp-server:dev

测试

# Run all tests
pytest

# Run with coverage
pytest --cov=databricks_mcp_server

# Run specific test categories
pytest tests/test_cli_tools.py
pytest tests/test_sdk_tools.py
pytest tests/test_integration.py

# Run tests in Docker
docker run --rm \
  -e DATABRICKS_HOST="test-host" \
  -e DATABRICKS_TOKEN="test-token" \
  databricks-mcp-server:latest pytest

代码质量

# Format code
ruff format .

# Lint code
ruff check .

# Type checking
mypy databricks_mcp_server/

# Security scanning
bandit -r databricks_mcp_server/

🔧 故障排除

常见问题

身份验证问题

# Verify connection
docker run --rm \
  -e DATABRICKS_HOST="your-host" \
  -e DATABRICKS_TOKEN="your-token" \
  databricks-mcp-server:latest \
  databricks auth describe

# Test with CLI
databricks clusters list

Docker问题

# Check container logs
docker logs databricks-mcp

# Debug container
docker run -it --rm \
  -e DATABRICKS_HOST="your-host" \
  -e DATABRICKS_TOKEN="your-token" \
  databricks-mcp-server:latest bash

常见错误解决方案

认证错误:
- 验证 DATABRICKS_HOST 格式（包括 https://)
- 检查PAT令牌权限和过期时间
- 确保工作区访问权限
未找到群集:
- 验证群集ID是否存在： databricks clusters list
- 检查群集权限
- 确保群集位于正确的工作区中
权限不足:
- 查看PAT令牌范围
- 检查工作区管理设置
- 验证Unity目录权限
超时错误:
- 增加环境变量中的超时值
- 检查网络连接
- 验证群集启动时间
Docker容器问题:
- 确保正确传递环境变量
- 检查Docker守护进程状态
- 验证映像构建是否成功完成

调试模式

启用详细日志记录：

# Environment variable
export DATABRICKS_MCP_LOG_LEVEL=DEBUG

# Docker run with debug
docker run --rm \
  -e DATABRICKS_MCP_LOG_LEVEL=DEBUG \
  -e DATABRICKS_HOST="your-host" \
  -e DATABRICKS_TOKEN="your-token" \
  databricks-mcp-server:latest

健康检查

# Test MCP server health
curl http://localhost:3000/health

# Test Databricks connectivity
docker exec databricks-mcp databricks auth describe

🤝 贡献

我们欢迎捐款！请按照以下步骤操作：

开发工作流程

分叉和克隆

git clone https://github.com/your-username/databricks-mcp-server.git
cd databricks-mcp-server

创建特征分支

git checkout -b feature/your-feature-name

设置开发环境

python -m venv venv
source venv/bin/activate
pip install -e ".[dev]"
pre-commit install

进行更改
- 在适当的文件中添加新工具(cli_tools.py, sdk_tools.py, hybrid_tools.py)
- 遵循现有的模式和命名约定
- 添加全面的文档字符串和类型提示

测试您的更改

pytest
ruff check .
mypy databricks_mcp_server/

提交拉取请求
- 确保所有测试通过
- 必要时更新文档
- 提供清晰的变更说明

贡献指南

代码的风格：遵循PEP 8，使用 ruff 用于格式化
测试：添加新功能的测试
文档：更新README和文档字符串
类型提示：全程使用类型注释
错误处理：实施适当的错误处理和日志记录

📄 许可证

此项目根据MIT许可证获得许可-请参阅许可证文件以获取详细信息。

🙏 致谢

copula 优秀的CLI和SDK
模型上下文协议对于MCP规范
FastMCP 对于服务器框架
开源社区的灵感和贡献