使用说明

基于节点的雪花MCP（注：MCP可能代表某种特定的系统、协议或概念，具体含义需根据上下文确定，此处保留原英文缩写）

一个基于TypeScript的MCP（模型上下文协议）服务器，它使得像Claude这样的大型语言模型（LLMs）能够直接查询和与Snowflake数据库进行交互。

🌟 特点

🔌（电源插头/插座） 轻松集成 - 使用Claude Desktop、Cursor或任何MCP兼容工具进行简单设置
🔒（锁形图标，通常表示安全、加密或锁定状态） 安全的 - 多种认证方法，包括环境变量和密钥对认证
🚀 表情符号“🚀”在中文中通常被理解为“火箭”或“快速前进”的意思，但直接翻译时，由于它是一个图形符号，没有固定的中文词汇对应，所以可以将其意译为“🚀（火箭/快速前进）”。不过，在实际使用中，人们往往直接保留这个表情符号，或者根据上下文用“火箭”、“飞速前进”等词语来描述其含义。 高性能 - 使用TypeScript和原生的Snowflake Node.js驱动程序构建
📊（表格/数据图表） 全面数据库访问 - 查询、探索模式、列出表和分析数据
🛠️（扳手，常用来表示修理、维护或工具） 对开发者友好 - 全面的TypeScript类型和错误处理

📋 前提条件

Node.js 18 或更高版本
npm 或 yarn
具有适当访问权限的Snowflake账户
兼容MCP的客户端（如Claude Desktop、Cursor、Continue等）

🚀 快速入门

安装选项

选项1：通过MCPB包安装（推荐用于Claude桌面版）

在Claude Desktop中安装此MCP服务器的最简单方法是使用预构建的MCPB包：

下载最新版本：
- 首选发布
- 下载 snowflake-mcp-v1.0.0.mcpb 文件
在Claude桌面端安装：
- 打开Claude桌面版
- 导航至设置 → 开发者 → MCP 服务器
- 点击“从文件安装”
- 选择已下载的 .mcpb 文件
- 当系统提示时，请配置您的 Snowflake 凭据

选项2：从源代码构建MCPB包

# Clone the repository
git clone https://github.com/patrickfreyer/mcp-server-snowflake.git
cd mcp-server-snowflake

# Install dependencies
npm install

# Build the TypeScript server
npm run build

# Create the MCPB package
./build-mcpb.sh

# The package will be created as snowflake-mcp-v1.0.0.mcpb
# Install this file in Claude Desktop as described above

选项3：手动安装（用于开发）

# Clone the repository
git clone https://github.com/patrickfreyer/mcp-server-snowflake.git
cd mcp-server-snowflake

# Install dependencies
npm install

# Build the server
npm run build

配置

配置取决于您的安装方法：

对于MCPB软件包用户

当你安装MCPB包时，Claude Desktop会自动提示你：

Snowflake 账户（例如。， your-account.region.provider）
仓库名称
用户名（通常是您的电子邮件）
密码
角色（可选）
数据库（可选）
模式（可选）

这些凭据安全地存储在Claude Desktop的配置中。

对于手动安装

设置环境变量：

# Copy the example environment file
cp .env.example .env

# Edit .env with your Snowflake credentials
SNOWFLAKE_ACCOUNT=your-account.region.provider
SNOWFLAKE_USER=your.email@company.com
SNOWFLAKE_PASSWORD=your-password
SNOWFLAKE_WAREHOUSE=YOUR_WAREHOUSE  # Optional
SNOWFLAKE_DATABASE=YOUR_DATABASE     # Optional
SNOWFLAKE_SCHEMA=YOUR_SCHEMA        # Optional
SNOWFLAKE_ROLE=YOUR_ROLE           # Optional

配置您的MCP客户端：

Claude Desktop（克劳德桌面版）

添加到 ~/Library/Application Support/Claude/claude_desktop_config.json:

{
  "mcpServers": {
    "snowflake": {
      "command": "node",
      "args": ["/absolute/path/to/mcp-server-snowflake/dist/index.js"],
      "env": {
        "SNOWFLAKE_ACCOUNT": "your-account.region.provider",
        "SNOWFLAKE_USER": "your.email@company.com",
        "SNOWFLAKE_PASSWORD": "your-password",
        "SNOWFLAKE_WAREHOUSE": "YOUR_WAREHOUSE",
        "SNOWFLAKE_DATABASE": "YOUR_DATABASE",
        "SNOWFLAKE_SCHEMA": "YOUR_SCHEMA",
        "SNOWFLAKE_ROLE": "YOUR_ROLE"
      }
    }
  }
}

光标

添加到光标设置中：

{
  "mcp.servers": {
    "snowflake": {
      "command": "node",
      "args": ["/path/to/mcp-server-snowflake/dist/index.js"],
      "env": {
        "SNOWFLAKE_ACCOUNT": "your-account",
        "SNOWFLAKE_USER": "your-user",
        "SNOWFLAKE_PASSWORD": "your-password"
      }
    }
  }
}

📚 可用工具

MCP服务器提供了以下工具用于与Snowflake进行交互：

`read_query`

在您的 Snowflake 数据库上执行 SELECT 查询。

// Example
{
  "query": "SELECT * FROM customers LIMIT 10"
}

`list_databases`

列出您Snowflake帐户中所有可用的数据库。

`list_schemas`

列出特定数据库中的所有架构。

// Example
{
  "database": "MY_DATABASE"  // Optional
}

`list_tables`

列出特定模式中的所有表。

// Example
{
  "database": "MY_DATABASE",  // Optional
  "schema": "MY_SCHEMA"       // Optional
}

`describe_table`

获取有关表结构的详细信息。

// Example
{
  "table_name": "DATABASE.SCHEMA.TABLE"
}

🔒 安全

环境变量

推荐的身份凭证方法：

export SNOWFLAKE_ACCOUNT="your-account"
export SNOWFLAKE_USER="your-user"
export SNOWFLAKE_PASSWORD="your-password"

密钥对认证（生产环境）

对于生产环境，我们建议使用密钥对认证：

生成一对密钥
使用公钥配置您的Snowflake用户
更新服务器配置以使用私钥

文件权限

保护好你的配置文件：

chmod 600 ~/.env
chmod 600 ~/Library/Application\ Support/Claude/claude_desktop_config.json

📦 构建MCPB包

MCPB（MCP 打包）格式使得在 Claude Desktop 中轻松分发和安装 MCP 服务器成为可能。

构建一个软件包

# Ensure the project is built
npm run build

# Create the MCPB package
./build-mcpb.sh

这将创建一个 snowflake-mcp-v1.0.0.mcpb 包含以下内容的文件：

编译后的服务器代码
带有配置架构的清单
生产依赖
安装元数据

包装内容

MCPB套件包含：

manifest.json - 定义配置参数和服务器入口点
dist/ - 编译后的TypeScript服务器代码
node_modules/ - 仅生产依赖
README.md - 软件包文档

显式配置

这个（或“该”） manifest.json 文件定义：

用户配置参数（出于安全考虑，不设默认值）
服务器入口点和环境变量映射
Snowflake操作的工具定义
包元数据（名称、版本、作者等）

🧪 开发

设置开发环境

# Install dependencies
npm install

# Run in development mode
npm run dev

# Run tests
npm test

# Lint code
npm run lint

# Type check
npm run type-check

项目结构

mcp-server-snowflake/
├── src/
│   └── index.ts          # Main server implementation
├── dist/                 # Compiled JavaScript (generated)
├── tests/               # Test files
├── .env.example         # Environment variable template
├── .github/
│   └── workflows/       # CI/CD workflows
├── manifest.json        # MCPB package configuration
├── build-mcpb.sh        # Script to build MCPB package
├── package.json         # Node.js dependencies
├── tsconfig.json        # TypeScript configuration
├── LICENSE             # MIT License
├── CONTRIBUTING.md     # Contribution guidelines
└── README.md          # This file

🤝 贡献

我们欢迎投稿！请参阅我们的贡献指南详情见下文。

如何做出贡献

克隆该仓库
创建你的特性分支（git checkout -b feature/AmazingFeature)
提交您的更改（git commit -m 'Add some AmazingFeature'）
推送到分支（git push origin feature/AmazingFeature)
提交拉取请求（或：创建拉取请求）

📝 许可证

这个项目遵循MIT许可证授权——详见许可证文件中包含详细信息。

🆘 支持

如果您遇到任何问题或有任何疑问：

检查一下故障排除以下部分
搜索现有问题
创建一个新问题

🔧 故障排除

常见问题

“缺少必需的Snowflake配置”

确保所有必需的环境变量都已设置
检查变量名中的拼写错误
验证 .env 文件是否位于正确的位置

连接失败

验证您的Snowflake帐户格式： account.region.provider
检查网络连接和防火墙设置
确保您的IP已在Snowflake网络策略中被加入白名单

权限被拒绝

验证您的Snowflake角色是否具有必要的权限
检查仓库访问权限
确保已授予数据库和架构的权限

调试模式

启用详细日志记录：

export DEBUG=mcp:*
node dist/index.js

🚀 路线图

[ ] 添加对写操作（INSERT、UPDATE、DELETE）的支持
[ ] 实现连接池
[ ] 添加对Snowflake存储过程的支持
[ ] 创建一个基于网页的配置用户界面
[ ] 添加对多个Snowflake账户的支持
[ ] 实现查询结果缓存
[ ] 添加数据可视化功能

👥 作者

帕特里克·弗雷尔 - 初步工作

🙏 致谢

Anthropic（公司名，可译为“安萨提克”或根据具体语境保留原名）针对MCP协议规范
雪花因其出色的Node.js SDK
开源社区为持续支持和贡献提供了平台

📊 统计数据

由 Patrick Freyer 用心制作