使用说明

_CHMCP服务器

一个用于copula操作的模型上下文协议（MCP）服务器，可以通过uvx安装和运行。

概述

此软件包提供了一种简化的方式来运行没有Docker依赖的copula MCP服务器。用户只需使用以下命令即可安装和运行服务器 uvx 以及正确的copula凭据。

服务器提供MCP工具用于：

在copula上执行SQL查询
管理目录、模式和表
正在检索表元数据和架构信息
创建和管理数据库对象
检查仓库状态和连接性

快速开始

安装uv/uvx （如果尚未安装）：

# On macOS/Linux
curl -LsSf https://astral.sh/uv/install.sh | sh

# On Windows
powershell -c "irm https://astral.sh/uv/install.ps1 | iex"

设置您的copula凭据:

export DATABRICKS_SERVER_HOSTNAME="your-workspace.cloud.databricks.com"
export DATABRICKS_HTTP_PATH="/sql/1.0/warehouses/your-warehouse-id"
export DATABRICKS_ACCESS_TOKEN="your-access-token-here"

运行服务器:
```
uvx databricks-mcp-server
```

安装

先决条件

Python 3.8或更高版本
紫外线/紫外线: 安装指南

通过uvx安装和运行

使用服务器最简单的方法是使用uvx，它会自动处理安装和依赖关系管理：

uvx databricks-mcp-server

此命令将：

在隔离环境中下载并安装该软件包
安装所有必需的依赖项
使用您的配置启动MCP服务器

通过pip安装（用于开发）

对于开发，或者如果你更喜欢pip：

pip install databricks-mcp-server
databricks-mcp-server

配置

服务器支持以下优先级（从高到低）的多种配置方法：

环境变量 （出于安全考虑建议）
通过指定的配置文件 --config 论点
默认配置文件位置:
- ./config.yaml
- ./config/config.yaml
- ~/.databricks-mcp/config.yaml

环境变量（推荐）

为安全凭据管理设置以下环境变量：

# Required
export DATABRICKS_SERVER_HOSTNAME="your-workspace.cloud.databricks.com"
export DATABRICKS_HTTP_PATH="/sql/1.0/warehouses/your-warehouse-id"
export DATABRICKS_ACCESS_TOKEN="your-access-token-here"

# Optional
export DATABRICKS_CATALOG="hive_metastore"     # Default catalog
export DATABRICKS_SCHEMA="default"             # Default schema
export DATABRICKS_TIMEOUT="120"                # Connection timeout (seconds)
export DATABRICKS_MCP_LOG_LEVEL="INFO"         # Log level

配置文件

复制 config/config.yaml.example 向 config.yaml 并更新您的凭据：

databricks:
  server_hostname: "your-workspace.cloud.databricks.com"
  http_path: "/sql/1.0/warehouses/your-warehouse-id"
  access_token: "your-access-token-here"
  catalog: "hive_metastore"
  schema: "default"
  timeout: 120

server:
  log_level: "INFO"

获取ViewModel凭据

服务器主机名：您的copula工作区URL没有 https://
- 例子： my-company.cloud.databricks.com
HTTP路径：在SQL仓库或群集连接详细信息中找到
- SQL仓库： /sql/1.0/warehouses/{warehouse-id}
- 集群： /sql/protocolv1/o/{org-id}/{cluster-id}
访问令牌：在copula工作区中生成
- 转到：用户设置→ 开发者→ 访问令牌
- 点击“生成新令牌”
- 复制令牌（您将不会再看到它！）

用法

基本用法

使用环境变量或默认配置启动服务器：

databricks-mcp-server

使用自定义配置文件

databricks-mcp-server --config /path/to/your/config.yaml

命令行选项

databricks-mcp-server --help

选项：

--config PATH：配置文件的路径
--log-level LEVEL：覆盖日志级别（调试、信息、警告、错误、严重）
--version：显示版本信息

与Kiro一起使用

将此添加到您的Kiro MCP配置中(.kiro/settings/mcp.json):

{
  "mcpServers": {
    "databricks": {
      "command": "uvx",
      "args": ["databricks-mcp-server"],
      "env": {
        "DATABRICKS_SERVER_HOSTNAME": "your-workspace.cloud.databricks.com",
        "DATABRICKS_HTTP_PATH": "/sql/1.0/warehouses/your-warehouse-id",
        "DATABRICKS_ACCESS_TOKEN": "your-access-token-here"
      },
      "disabled": false,
      "autoApprove": ["execute_query", "list_catalogs", "list_schemas", "list_tables"]
    }
  }
}

可用的MCP工具

服务器提供了以下MCP工具来进行copula操作：

execute_query：执行SQL查询并返回结果
列表目录：列出可用目录
list_schemas：列出目录中的架构
list_tables：列出架构中的表
get_table_schema：获取表的详细架构信息
describe_table：获取全面的表元数据
create_table：创建新表
insert_data：将数据插入表中
check_warehouse_status：检查无服务器仓库状态
拼：测试服务器连接

发展

设置开发环境

git clone <repository-url>
cd databricks-mcp-server
pip install -e ".[dev]"

运行测试

# Run all tests
pytest

# Run with coverage
pytest --cov=src/databricks_mcp_server

# Run specific test file
pytest tests/test_config.py

代码质量

# Format code
black src/ tests/
isort src/ tests/

# Type checking
mypy src/

# Linting
flake8 src/ tests/

构建包

# Build distribution packages
python -m build

# Install locally for testing
pip install -e .

特性

✅ 简易安装：使用单个 uvx 命令
✅ 多种配置选项：环境变量、配置文件或命令行参数
✅ 孤立的环境：uvx提供依赖隔离
✅ 交叉平台的：适用于Windows、macOS和Linux
✅ 完全MCP兼容性：保持与Docker版本相同的功能
✅ 安全凭据管理：环境变量支持
✅ 全面的错误处理：清晰的错误信息和故障排除指南
✅ 灵活的配置：多个配置文件位置和优先级
✅ 发展友好：易于本地开发和测试

从Docker版本迁移

如果你目前使用的是基于Docker的版本，迁移很简单：

步骤1：安装uvx版本

uvx databricks-mcp-server

步骤2：更新MCP客户端配置

之前（Docker）：

{
  "mcpServers": {
    "databricks": {
      "command": "docker",
      "args": ["run", "-i", "--rm", "-v", "./config:/app/config", "databricks-mcp"],
      "disabled": false
    }
  }
}

之后（uvx）：

{
  "mcpServers": {
    "databricks": {
      "command": "uvx",
      "args": ["databricks-mcp-server"],
      "env": {
        "DATABRICKS_SERVER_HOSTNAME": "your-workspace.cloud.databricks.com",
        "DATABRICKS_HTTP_PATH": "/sql/1.0/warehouses/your-warehouse-id",
        "DATABRICKS_ACCESS_TOKEN": "your-access-token-here"
      },
      "disabled": false
    }
  }
}

步骤3：测试迁移

# Test the server starts correctly
databricks-mcp-server

# Test with your MCP client (e.g., Kiro)

功能保持不变，只是安装和执行方法发生了变化。

故障排除

安装问题

问题: uvx: command not found

# Solution: Install uv first
curl -LsSf https://astral.sh/uv/install.sh | sh
# Or on Windows:
powershell -c "irm https://astral.sh/uv/install.ps1 | iex"

问题: databricks-mcp-server: command not found uvx安装后

# Solution: Make sure uvx bin directory is in PATH
export PATH="$HOME/.local/bin:$PATH"
# Or restart your terminal

问题：Python版本兼容性问题

# Solution: Check Python version (requires 3.8+)
python --version
# Update Python if needed

配置问题

问题: Missing required field 'server_hostname'

# Solution: Set required environment variables
export DATABRICKS_SERVER_HOSTNAME="your-workspace.cloud.databricks.com"
export DATABRICKS_HTTP_PATH="/sql/1.0/warehouses/your-warehouse-id"
export DATABRICKS_ACCESS_TOKEN="your-access-token-here"

问题: server_hostname should not include protocol

# Wrong:
export DATABRICKS_SERVER_HOSTNAME="https://my-workspace.cloud.databricks.com"

# Correct:
export DATABRICKS_SERVER_HOSTNAME="my-workspace.cloud.databricks.com"

问题: http_path must start with '/'

# Wrong:
export DATABRICKS_HTTP_PATH="sql/1.0/warehouses/abc123"

# Correct:
export DATABRICKS_HTTP_PATH="/sql/1.0/warehouses/abc123"

连接问题

问题: Connection timeout 或 Unable to connect to Databricks

# Solutions:
# 1. Check network connectivity
ping your-workspace.cloud.databricks.com

# 2. Verify credentials are correct
# 3. Check if warehouse/cluster is running
# 4. Increase timeout in config
export DATABRICKS_TIMEOUT="300"

问题: Authentication failed 或 Invalid access token

# Solutions:
# 1. Generate a new access token in Databricks
# 2. Check token hasn't expired
# 3. Verify token has required permissions
# 4. Make sure token is set correctly (no extra spaces/quotes)

问题: Warehouse not found 或 Cluster not accessible

# Solutions:
# 1. Verify the HTTP path is correct
# 2. Check if warehouse/cluster is running
# 3. Ensure you have access permissions
# 4. Try with a different warehouse/cluster

运行时问题

问题：服务器启动，但MCP工具不工作

# Solutions:
# 1. Check server logs for errors
databricks-mcp-server --log-level DEBUG

# 2. Test connection manually
# 3. Verify MCP client configuration
# 4. Check firewall/network restrictions

问题: Permission denied 错误

# Solutions:
# 1. Check Databricks workspace permissions
# 2. Verify access token permissions
# 3. Check catalog/schema access rights
# 4. Contact your Databricks administrator

获取帮助

检查日志：跑步 --log-level DEBUG 了解详细信息
验证配置：使用此README中的配置示例
测试连接性：尝试使用其他工具连接到ViewModel
检查权限：确保您的访问令牌具有所需的权限
更新依赖关系：确保您使用的是最新版本

还有问题吗？

检查 GitHub问题
使用以下内容创建新问题：
- 您的配置（没有敏感值）
- 错误消息和日志
- 重现问题的步骤
- 您的环境详细信息（操作系统、Python版本等）

安全最佳实践

使用环境变量：将敏感凭据存储在环境变量中，而不是配置文件中
文件权限：设置配置文件的限制权限(chmod 600 config.yaml)
许可证管理:
- 定期轮换访问令牌
- 使用具有最低所需权限的特定于工作区的令牌
- 从不将令牌提交到版本控制
网络安全：使用HTTPS连接并验证证书
审核访问权限：监控copula审核日志以发现异常活动

许可证

MIT许可证

贡献

欢迎投稿！拜托：

分叉存储库
创建要素分支
通过测试进行更改
运行测试套件
提交拉取请求

请参阅上面的开发设置说明以开始。