OSS Snowflake MCP Server

[已弃用] Snowflake Cortex AI Model Context Protocol（MCP）服务

注意

此项目已弃用，不再维护。 请迁移至官方 Snowflake MCP Server。Snowflake 正在积极开发官方服务，并为其提供全面支持，且持续添加新功能。

此社区 MCP 服务此前为 Snowflake Cortex AI、对象管理和 SQL 编排提供工具。该服务已不再受支持。对于所有新的和现有的用例，请改用官方 Snowflake MCP Server。

agent_services: # List all Cortex Agent services
  - service_name: <service_name>
    description: > # Describe contents of the agent service
      <Agent service that ...>
    database_name: <database_name>
    schema_name: <schema_name>
  - service_name: <service_name>
    description: > # Describe contents of the agent service
      <Agent service that ...>
    database_name: <database_name>
    schema_name: <schema_name>
search_services: # List all Cortex Search services
  - service_name: <service_name>
    description: > # Describe contents of the search service
      <Search services that ...>
    database_name: <database_name>
    schema_name: <schema_name>
  - service_name: <service_name>
    description: > # Describe contents of the search service
      <Search services that ...>
    database_name: <database_name>
    schema_name: <schema_name>
analyst_services: # List all Cortex Analyst semantic models/views
  - service_name: <service_name> # Create descriptive name for the service
    semantic_model: <semantic_yaml_or_view> # Fully-qualify semantic YAML model or Semantic View
    description: > # Describe contents of the analyst service
      <Analyst service that ...>
  - service_name: <service_name> # Create descriptive name for the service
    semantic_model: <semantic_yaml_or_view> # Fully-qualify semantic YAML model or Semantic View
    description: > # Describe contents of the analyst service
      <Analyst service that ...>
other_services: # Set desired tool groups to True to enable tools for that group
  object_manager: True # Perform basic operations against Snowflake's most common objects such as creation, dropping, updating, and more.
  query_manager: True # Run LLM-generated SQL managed by user-configured permissions.
  semantic_manager: True # Discover and query Snowflake Semantic Views and their components.
sql_statement_permissions: # List SQL statements to explicitly allow (True) or disallow (False).
  # - All: True # To allow everything, uncomment and set All: True.
  - Alter: True
  - Command: True
  - Comment: True
  - Commit: True
  - Copy: True
  - Create: True
  - Delete: True
  - Describe: True
  - Drop: True
  - Insert: True
  - Merge: True
  - Rollback: True
  - Select: True
  - Transaction: True
  - TruncateTable: True
  - Unknown: False # To allow unknown or unmapped statement types, set Unknown: True.
  - Update: True
  - Use: True

MCP 服务使用 Snowflake Python Connector 进行所有身份验证和连接。有关全面的身份验证选项和最佳实践，请参阅 Snowflake 官方文档。

MCP 服务遵循指定角色（通过连接参数传递）或用户的默认角色（未传递角色进行连接时）所分配的 RBAC 权限。

连接参数可以通过 CLI 参数和／或环境变量传递。服务支持 Snowflake Python Connector 提供的所有身份验证方式，包括：

• 用户名／密码身份验证
• 密钥对身份验证
• OAuth 身份验证
• 单点登录（SSO）
• 多重身份验证（MFA）

连接参数

连接参数可以通过 CLI 参数和／或环境变量传递：

警告

弃用通知：CLI 参数 --account-identifier 和 --pat，以及环境变量 SNOWFLAKE_PAT 已弃用，并将在未来版本中移除。请改用 --account 和 --password（或 SNOWFLAKE_ACCOUNT 和 SNOWFLAKE_PASSWORD）。

传输配置

MCP 服务支持多种传输机制。有关 MCP 传输的详细信息，请参阅 FastMCP 传输协议。

用法

# Default stdio transport
uvx snowflake-labs-mcp --service-config-file config.yaml

# HTTP transport with custom endpoint
uvx snowflake-labs-mcp --service-config-file config.yaml --transport streamable-http --endpoint /my-endpoint

# For containers (uses streamable-http on port 9000)
uvx snowflake-labs-mcp --service-config-file config.yaml --transport streamable-http --endpoint /snowflake-mcp

传输自定义配置

可用于 sse 和 streamable-http 传输的服务自定义配置：

示例：

export SNOWFLAKE_MCP_ENDPOINT="/my-mcp"
uvx snowflake-labs-mcp --service-config-file config.yaml --transport streamable-http

与 MCP 客户端配合使用

MCP 服务不依赖特定客户端，可与大多数支持 MCP 工具基本功能和（可选）资源的 MCP 客户端配合使用。以下是本地安装的示例。有关连接到容器化部署的说明，请参阅将 MCP 客户端连接到容器。

Claude Desktop

要将此服务作为 MCP 客户端集成到 Claude Desktop 中，请将以下内容添加到应用的服务配置中。默认位置如下：

• macOS：~/Library/Application Support/Claude/claude_desktop_config.json
• Windows：%APPDATA%\Claude\claude_desktop_config.json

设置服务配置文件的路径并配置连接方式：

{
  "mcpServers": {
    "mcp-server-snowflake": {
      "command": "uvx",
      "args": [
        "snowflake-labs-mcp",
        "--service-config-file",
        "<path_to_file>/tools_config.yaml",
        "--connection-name",
        "default"
      ]
    }
  }
}

Cursor

在 Cursor 中打开设置，依次进入 Settings -> Cursor Settings -> MCP，按以下内容注册 MCP 服务：

{
  "mcpServers": {
    "mcp-server-snowflake": {
      "command": "uvx",
      "args": [
        "snowflake-labs-mcp",
        "--service-config-file",
        "<path_to_file>/tools_config.yaml",
        "--connection-name",
        "default"
      ]
    }
  }
}

在聊天中将 MCP 服务添加为上下文。

如需排查 Cursor 服务问题，请打开 Output 面板，并从下拉菜单中选择 Cursor MCP，查看日志。

fast-agent

在 fastagent.config.yaml 的 mcp 服务部分中，填写配置文件路径和连接名称：

# MCP Servers
mcp:
    servers:
        mcp-server-snowflake:
            command: "uvx"
            args: ["snowflake-labs-mcp", "--service-config-file", "<path_to_file>/tools_config.yaml", "--connection-name", "default"]

Microsoft Visual Studio Code + GitHub Copilot

有关先决条件、环境设置、分步指南和说明，请参阅这篇 博客。

Codex

在 codex 中添加以下内容到 ~/.codex/config.toml，以注册 MCP 服务。

[mcp_servers.mcp-server-snowflake]
command = "uvx"
args = [
    "snowflake-labs-mcp",
    "--service-config-file",
    "<path_to_file>/tools_config.yaml",
    "--connection-name",
    "default"
]

编辑后，在终端运行 codex mcp list，输出中应显示 snowflake mcp。

容器部署

将 MCP 服务部署为容器，以便远程访问或用于生产环境。本指南将逐步介绍 Docker 和 Docker Compose 部署方法。

Docker 部署

按照以下步骤使用 Docker 部署 MCP 服务：

步骤 1：准备配置文件

创建 MCP 配置目录并复制模板：

mkdir -p ${HOME}/.mcp/
cp services/configuration.yaml ${HOME}/.mcp/tools_config.yaml

步骤 2：配置服务

编辑配置文件以匹配你的环境：

# Edit the configuration file as needed
# Update service names, database/schema references, and enable desired features
nano ${HOME}/.mcp/tools_config.yaml

步骤 3：构建容器镜像

使用提供的 Dockerfile 构建 Docker 镜像：

docker build -f docker/server/Dockerfile -t mcp-server-snowflake .

步骤 4：设置环境变量

配置 Snowflake 连接参数。选择以下一种身份验证方法：

用户名/密码身份验证：

export SNOWFLAKE_ACCOUNT=<your_account>
export SNOWFLAKE_USER=<your_username>
export SNOWFLAKE_PASSWORD=<your_password>

密钥对身份验证：

export SNOWFLAKE_ACCOUNT=<your_account>
export SNOWFLAKE_USER=<your_username>
export SNOWFLAKE_PRIVATE_KEY="$(cat <path_to_private_key.p8>)"
export SNOWFLAKE_PRIVATE_KEY_FILE_PWD=<your_key_password>

步骤 5：运行容器

使用配置和环境变量启动容器：

用户名/密码身份验证：

docker run -d \
  --name mcp-server-snowflake \
  -p 9000:9000 \
  -e SNOWFLAKE_ACCOUNT=${SNOWFLAKE_ACCOUNT} \
  -e SNOWFLAKE_USER=${SNOWFLAKE_USER} \
  -e SNOWFLAKE_PASSWORD=${SNOWFLAKE_PASSWORD} \
  -v ${HOME}/.mcp/tools_config.yaml:/app/services/tools_config.yaml:ro \
  mcp-server-snowflake

密钥对身份验证：

docker run -d \
  --name mcp-server-snowflake \
  -p 9000:9000 \
  -e SNOWFLAKE_ACCOUNT=${SNOWFLAKE_ACCOUNT} \
  -e SNOWFLAKE_USER=${SNOWFLAKE_USER} \
  -e SNOWFLAKE_PRIVATE_KEY="${SNOWFLAKE_PRIVATE_KEY}" \
  -e SNOWFLAKE_PRIVATE_KEY_FILE_PWD=${SNOWFLAKE_PRIVATE_KEY_FILE_PWD} \
  -v ${HOME}/.mcp/tools_config.yaml:/app/services/tools_config.yaml:ro \
  mcp-server-snowflake

步骤 6：验证部署

检查容器是否正在运行且可访问：

# Check container status
docker ps

# Check container logs
docker logs mcp-server-snowflake

# Test endpoint (should return MCP server info)
curl http://localhost:9000/snowflake-mcp

Docker Compose 部署

按照以下步骤使用 Docker Compose 简化部署：

步骤 1：准备配置文件

创建配置目录并复制模板：

mkdir -p ${HOME}/.mcp/
cp services/configuration.yaml ${HOME}/.mcp/tools_config.yaml

步骤 2：配置服务

编辑配置文件以匹配你的环境：

# Update service configurations as needed
nano ${HOME}/.mcp/tools_config.yaml

步骤 3：设置环境变量

配置 Snowflake 连接参数：

export SNOWFLAKE_ACCOUNT=<your_account>
export SNOWFLAKE_USER=<your_username>
# For username/password auth:
export SNOWFLAKE_PASSWORD=<your_password>
# For key pair auth, also set:
# export SNOWFLAKE_PRIVATE_KEY="$(cat <path_to_private_key.p8>)"
# export SNOWFLAKE_PRIVATE_KEY_FILE_PWD=<your_key_password>

步骤 4：启动服务

使用 Docker Compose 启动容器：

docker-compose up -d

步骤 5：验证部署

检查服务是否正在运行：

# Check service status
docker-compose ps

# View logs
docker-compose logs

# Test endpoint
curl http://localhost:9000/snowflake-mcp

将 MCP 客户端连接到容器

MCP 服务在容器中运行后，你可以将各种 MCP 客户端连接到它。所有客户端的连接配置都相同，只有配置格式不同。

连接 URL 格式：

• 本地部署：http://localhost:9000/snowflake-mcp
• 远程部署：http://<hostname>:<port>/snowflake-mcp

Claude Desktop

将以下内容添加到 claude_desktop_config.json：

{
  "mcpServers": {
    "mcp-server-snowflake": {
      "url": "http://localhost:9000/snowflake-mcp"
    }
  }
}

Cursor

将以下内容添加到 Cursor 中的 MCP 设置（Settings -> Cursor Settings -> MCP）：

{
  "mcpServers": {
    "mcp-server-snowflake": {
      "url": "http://localhost:9000/snowflake-mcp"
    }
  }
}

fast-agent

将以下内容添加到你的 fastagent.config.yaml 中：

# MCP Servers
mcp:
    servers:
        mcp-server-snowflake:
            url: "http://localhost:9000/snowflake-mcp"

注意：

• 对于远程部署，请将 localhost:9000 替换为服务器的主机名和端口
• 确保防火墙允许通过端口 9000（或你配置的端口）建立连接
• 对于生产部署，请考虑使用 HTTPS 和适当的身份验证

Cortex 服务

配置文件中 Cortex Agent（位于 agent_services 部分）、Cortex Search（位于 search_services 部分）和 Cortex Analyst（位于 analyst_services 部分）的实例都将作为工具提供。将这些部分留空即可省略相应工具。

MCP 服务仅支持 Cortex Agent 对象。也就是说，只有在 Snowflake 中预先配置的 Cortex Agent 对象才能用作工具。更多详情请参阅 Cortex Agent Run API。

确保所有服务的上下文名称准确无误，包括服务名称、数据库、架构等。理想的描述应当详尽且彼此互斥。

分析服务中的 semantic_model 值应为完全限定的语义视图，或 Snowflake 暂存区中的语义 YAML 文件：

• 对于语义视图：MY_DATABASE.MY_SCHEMA.MY_SEMANTIC_VIEW
• 对于语义 YAML 文件：@MY_DATABASE.MY_SCHEMA.MY_STAGE/my_semantic_file.yaml（注意 @。）

对象管理

MCP 服务包含数十种工具，专门用于执行基本的操作管理。对于高级对象管理，建议直接使用 Snowsight。

MCP 服务目前支持以下对象类型的创建、删除、创建或修改、描述和列出操作。 要启用这些工具，请在配置文件的 other_services 部分将 object_manager 设为 True。

- Database
- Schema
- Table
- View
- Warehouse
- Compute Pool
- Role
- Stage
- User
- Image Repository

请注意，这些工具同样受配置文件中 sql_statement_permissions 部分所配置权限的管理。 用于创建和创建或修改对象的对象管理工具受 Create 权限管理。删除对象受 Drop 权限管理。

未来版本中可能会加入更多操作和对象。

SQL 执行

通用 SQL 工具可执行由 MCP 客户端生成的通用 SQL 语句。用户可以完全控制配置文件中允许执行的 SQL 语句类型。

配置文件中的 sql_statement_permissions 列出了 sqlglot 表达式类型。标记为 False 的类型会在执行前被拦截。标记为 True 的类型将会执行（或根据 MCP 客户端设置提示用户确认执行）。

要启用 SQL 执行工具，请在 other_services 下的配置文件中将 query_manager 设为 True。 要允许所有 SQL 表达式通过额外验证，请将 All 设为 True。

并非所有 Snowflake SQL 命令都映射到了 sqlglot 中，因此你可能会发现一些不常见的命令尚未被收录在配置文件中。 将 Unknown 设为 True，即可允许这些未收录的命令通过额外验证。 你也可以直接添加新的表达式类型，以允许特定类型的表达式。

以下是一些 sqlglot 表达式类型及相应的 Snowflake SQL 命令示例：

语义视图查询

多个工具支持发现和查询 Snowflake 语义视图及其组件。 语义视图可以列出和描述。此外，你还可以列出其指标和维度。 最后，你可以直接**查询语义视图**。

要启用这些工具，请在 other_services 下的配置文件中将 semantic_manager 设为 True。

故障排除

运行 MCP Inspector

MCP Inspector 是一款功能强大的调试工具，提供 Web 界面，可直接与 MCP 服务交互。它对于排查配置问题、测试工具和验证设置至关重要。

Inspector 基本用法

使用 MCP 服务配置启动 Inspector：

npx @modelcontextprotocol/inspector uvx snowflake-labs-mcp --service-config-file <path_to_file>/tools_config.yaml --connection-name "default"

检查器会向你展示什么

启动后，检查器会打开一个 Web 界面，你可以在其中：

1. 查看可用工具：查看从配置文件加载的所有 MCP 工具
2. 测试工具执行：使用自定义参数直接调用工具，以验证其是否正常工作
3. 检查资源：查看服务公开的所有资源
4. 排查连接问题：如果连接失败，查看详细的错误消息
5. 验证配置：确保服务配置已正确加载

常见故障排查场景

配置文件问题：

• 如果工具未显示，请检查 tools_config.yaml 语法
• 确认服务名称以及数据库／架构引用正确
• 确保你想要的工具组已将 other_services 设为 True

连接问题：

• 确认 Snowflake 连接参数正确
• 检查你的角色是否具有你所配置服务所需的权限
• 如果使用密钥对身份验证，请确保私钥格式正确

工具执行错误：

• 使用检查器，通过已知有效的参数测试单个工具
• 查看服务日志，了解详细的错误消息
• 确认底层 Snowflake 对象（数据库、架构、服务）存在

其他调试方法

使用 Cursor MCP 日志：

• 在 Cursor 中打开输出面板
• 从下拉菜单中选择“Cursor MCP”
• 与 MCP 服务交互时查看实时日志

命令行调试：

使用 --verbose 启用调试日志，或将 SNOWFLAKE_MCP_VERBOSE=true 设为环境变量：

uvx snowflake-labs-mcp --service-config-file <path_to_file>/tools_config.yaml --connection-name "default" --verbose

常见问题

如何连接到 Snowflake？

• MCP 服务支持 Snowflake Python Connector 支持的所有连接方式。 请参阅使用 Python Connector 连接到 Snowflake了解更多信息。

我收到了工具数量限制错误／警告。

• 虽然大模型支持更多工具的能力可能会不断提升，但你可以在配置文件中将工具组设为 False，以隐藏这些工具组。 此外，只有列出的 Cortex 服务才会被转换为工具。

我可以使用程序化访问令牌（PAT）代替密码吗？

• 可以。将其传递给 CLI 标志 --password，或将其设为环境变量 SNOWFLAKE_PASSWORD。

如何试用？

• MCP 服务旨在作为 MCP 生态系统的一部分使用。你可以将其视为一组工具。你需要一个 MCP 客户端来充当协调器。请参阅 MCP 简介了解更多信息。

此服务部署在哪里？它运行在 Snowpark Container Services 中吗？

• 此 MCP 服务中的所有工具都是托管服务，可通过 REST API 访问。无需单独部署远程服务。当前版本的服务旨在由 MCP 客户端（例如 Claude Desktop、Cursor、fast-agent 等）启动。将服务配置到这些 MCP 客户端后，应用程序会为你启动服务。未来版本的 MCP 服务可能会部署为远程服务。

调用工具时收到了权限错误。

• 如果使用程序化访问令牌，请注意，它们不会评估辅助角色。创建令牌时，请选择一个有权访问所有服务及其底层对象的角色，或选择任意角色。若要更改此属性，需要创建新的 PAT。

我可以添加多少个 Cortex Search 或 Cortex Analysts？

• 你可以添加多个这两类服务的实例。MCP 客户端会根据用户的提示词决定使用哪些实例。

救命！我遇到了 SSLError？

• 如果你的账户名称包含下划线，请尝试使用 URL 中带连字符的版本。
  • 包含下划线的账户标识符：acme-marketing_test_account
  • 包含连字符的账户标识符：acme-marketing-test-account

如何在容器中运行 MCP 服务以供多个用户使用？

• 按照容器部署部分所示，使用 Docker 或 Docker Compose 进行部署。容器化的服务通过 HTTP 运行，可处理多个并发 MCP 客户端连接。配置用于身份验证的环境变量，并将配置文件挂载为只读卷。

为什么我的 Cortex 服务没有显示为工具？

• 确认配置文件语法正确（使用 MCP Inspector 验证）。
• 确保服务名称、数据库名称和架构名称与 Snowflake 中的实际名称完全一致。
• 检查你的角色是否有权访问指定的数据库和架构。
• 确认指定位置中确实存在这些 Cortex 服务。

我可以在不同环境中使用不同的身份验证方法吗？

• 可以。你可以为每个部署设置不同的环境变量，在 connections.toml 文件中使用不同的连接名称，或传入不同的 CLI 参数。该服务支持 Snowflake Python Connector 的所有身份验证方法，包括用户名/密码、密钥对、OAuth 和 SSO。

如何限制可执行的 SQL 语句？

• 使用配置文件中的 sql_statement_permissions 部分。将特定语句类型设为 True（允许）或 False（拒绝）。为确保最高安全性，只启用你实际需要的语句类型。将 Unknown 设为 False，以阻止无法识别的语句类型。

MCP 服务启动缓慢。这正常吗？

• 服务首次启动时，需要连接到 Snowflake 并验证配置，因此可能需要几秒钟。之后调用工具的速度应该会快得多。如果启动时间超过 30 秒，请检查与 Snowflake 的网络连接，并确认身份验证凭据无误。