使用说明

项目简介

Zaturn 是一个开源的、AI 驱动的数据分析工具，它以 MCP (Model Context Protocol) 服务器 的形式运行，可以连接到您的各种数据源，执行 SQL 查询，并为大型语言模型 (LLM) 客户端提供有用的数据洞察。您可以将其集成到支持 MCP 协议的 LLM 客户端（如 Claude、Cursor 等）中使用，让 AI 能够访问和分析您的数据。

主要功能点

数据源连接: 支持连接多种数据源，包括 SQLite, DuckDB 等 SQL 数据库以及 CSV, Parquet 等文件。未来计划支持更多数据源如 MySQL, PostgreSQL, Excel, JSON, GIS 数据等。
SQL 查询执行: 允许 LLM 客户端通过工具调用执行 SQL 查询，从而分析数据源中的数据。
数据洞察: 通过执行 SQL 查询，Zaturn 能够提取数据中的关键信息，并以结构化的方式返回给 LLM，辅助 LLM 理解和分析数据。
MCP 服务器: 作为一个标准的 MCP 服务器，Zaturn 可以无缝集成到任何支持 MCP 协议的 LLM 客户端中，为 AI 应用提供数据上下文。

安装步骤

安装 uv: uv 是一个快速的 Python 包安装和管理工具。请根据您的操作系统，参考 uv 官方文档进行安装。

克隆 Zaturn 仓库: 使用 git 命令克隆 Zaturn 代码仓库到本地：

git clone https://github.com/kdqed/zaturn.git

服务器配置

要将 Zaturn MCP 服务器集成到您的 MCP 客户端，您需要在客户端的 MCP 配置中添加 Zaturn 服务器的配置信息。以下是一个示例配置，您需要根据您的实际情况修改路径：

"mcpServers": {
  "zaturn": {
    "command": "uv",
    "args": [
      "run",
      "--directory",
      "/path/to/downloaded/folder",  // 替换为 Zaturn 仓库的本地路径
      "mcp_server.py",
      "sqlite:////full/path/to/sample_dbs/northwind.db", // 数据源 1: SQLite 数据库连接字符串 (绝对路径)
      "/full/path/to/sample_dbs/titanic.parquet",      // 数据源 2: Parquet 文件路径 (绝对路径)
      "/full/path/to/sample_dbs/ny_aq.csv",         // 数据源 3: CSV 文件路径 (绝对路径)
      "/full/path/to/sample_dbs/duckdb_sample.duckdb" // 数据源 4: DuckDB 数据库文件路径 (绝对路径)
    ]
  }
}

配置参数说明:

'"command": "uv"': 指定启动 Zaturn 服务器的命令为 'uv run'。
'"args"': 启动参数列表，包括：
- '"run"': 'uv run' 命令的子命令，用于运行 Python 脚本。
- '"--directory"': 指定 Zaturn 代码仓库的根目录。请将 '/path/to/downloaded/folder' 替换为您实际下载 Zaturn 仓库的本地绝对路径。
- '"mcp_server.py"': 指定要运行的 Python 脚本为 'mcp_server.py'，这是 Zaturn MCP 服务器的入口文件。
- '"sqlite:////full/path/to/sample_dbs/northwind.db"', '/full/path/to/sample_dbs/titanic.parquet', '/full/path/to/sample_dbs/ny_aq.csv', '/full/path/to/sample_dbs/duckdb_sample.duckdb': 这些是 数据源参数，您可以根据需要添加或修改。
  - 数据库连接字符串: 例如 'sqlite:////full/path/to/your_database.db' (SQLite 数据库绝对路径), 'mysql://user:password@host:port/database' (MySQL 连接字符串), 'postgresql://user:password@host:port/database' (PostgreSQL 连接字符串) 等。
  - 文件路径: 例如 '/full/path/to/your_data.csv' (CSV 文件绝对路径), '/full/path/to/your_data.parquet' (Parquet 文件绝对路径)。
  - DuckDB 数据库文件: 例如 '/full/path/to/your_duckdb.duckdb' (DuckDB 数据库文件绝对路径)。
  - 请注意: 所有文件路径都需要使用 绝对路径。您可以根据您的数据源情况，添加或删除数据源参数。

基本使用方法

配置系统提示 (System Prompt) (如果您的 LLM 客户端支持): 为了让 LLM 更好地利用 Zaturn 提供的数据分析能力，建议您设置如下系统提示：

You are a helpful data analysis assistant. Use only the tool provided data sources to process user inputs. Do not use external sources or your own knowledge base.

向 LLM 提问: 在您的 LLM 客户端中，像正常对话一样提问关于数据分析的问题。例如：
```
User: List the top 5 customers by revenue for Northwind
```
LLM 客户端会自动将请求转发给 Zaturn MCP 服务器，执行相应的工具调用，并最终将分析结果返回给您。

现在，您就可以开始使用 Zaturn 来分析您的数据了！

关键词