使用说明

项目简介

DuckDB Parquet MCP Server 是一个基于 Model Context Protocol (MCP) 的服务器实现，专注于为大型语言模型 (LLM) 提供对 Parquet 数据文件的上下文访问能力。它使用 DuckDB 数据库引擎作为后端，能够高效地查询和分析 Parquet 格式的数据文件，并将数据模式、查询工具和分析 Prompt 以标准化的 MCP 协议形式暴露给客户端。

主要功能点

数据模式资源: 以资源的形式提供已加载 Parquet 文件的表结构信息，方便 LLM 理解数据内容。
SQL 查询工具: 提供执行 SQL 查询的工具，允许 LLM 通过调用工具来查询 Parquet 文件中的数据。
数据分析 Prompt: 内置用于数据分析的 Prompt 模板，例如数据概览、趋势分析、异常值检测等，帮助用户快速开始数据分析任务。
SQL 生成 Prompt: 内置用于生成 SQL 查询语句的 Prompt 模板，辅助用户编写 SQL 查询。
灵活的文件输入: 支持多种 Parquet 文件来源，包括本地文件、本地目录、Google Cloud Storage (GCS) 存储桶目录，并支持递归目录扫描和混合数据源。

安装步骤

克隆仓库到本地:

git clone https://github.com/dwarvesf/mcp-duckdb
cd mcp-duckdb

安装依赖: 确保已安装 Node.js 和 npm，然后运行以下命令安装项目依赖：
```
npm install
```

服务器配置

MCP 服务器需要配置到 MCP 客户端中才能使用，以下是 Claude Desktop 客户端的服务器配置示例（其他 MCP 客户端配置方式类似）：

打开 Claude Desktop 的配置文件 'claude_desktop_config.json'，通常位于：

macOS: '~/Library/Application Support/Claude/claude_desktop_config.json'
Windows: '%APPDATA%\Claude\claude_desktop_config.json'

在 'mcpServers' 字段中添加以下配置，以注册 DuckDB Parquet MCP Server：

{
  "mcpServers": {
    "duckdb-parquet": {  // 服务器名称，可以自定义
      "command": "node",  // 启动服务器的命令，这里使用 node 运行 JavaScript 文件
      "args": [
        "/absolute/path/to/mcp-duckdb/src/index.js", //  服务器入口文件 index.js 的绝对路径，请替换为实际路径
        "--file", "/path/to/file1.parquet",         //  指定要加载的 Parquet 文件路径，可以替换为实际文件路径，支持多个 --file 参数
        "--gcs-bucket", "my-bucket",                //  指定要加载的 GCS 存储桶名称，可以替换为实际存储桶名称
        "--gcs-dir", "data/2023"                      //  指定要加载的 GCS 存储桶目录，可以替换为实际目录，支持多个 --gcs-dir 参数
        // 可以根据需要添加其他命令行参数，例如 --dir, --recursive 等
      ]
    }
  }
}

参数说明:

'command': 指定启动服务器的命令，这里是 'node'，表示使用 Node.js 运行 JavaScript 文件。
'args': 启动服务器的命令行参数，以数组形式提供。
- 第一个参数是服务器入口文件 'src/index.js' 的绝对路径，请务必替换为实际的绝对路径。
- '--file <path>': 指定要加载的 Parquet 文件路径。可以使用多个 '--file' 参数加载多个文件。
- '--dir <path>': 指定要扫描 Parquet 文件的本地目录。
- '--gcs-bucket <name>': 指定要访问的 Google Cloud Storage 存储桶名称。
- '--gcs-dir <path>': 指定要扫描 Parquet 文件的 GCS 存储桶目录。可以使用多个 '--gcs-dir' 参数加载多个目录。
- '--recursive': 启用递归目录扫描，用于扫描目录及其子目录下的 Parquet 文件。

请根据实际情况修改 'command' 和 'args' 中的路径和参数。

基本使用方法

启动服务器: 配置完成后，MCP 服务器会随着 MCP 客户端的启动而自动启动。
资源访问: 客户端可以通过以下 URI 访问服务器提供的资源：
- 'schema://list': 获取所有已加载 Parquet 文件的表结构信息列表。
- 'schema://{tableName}': 获取指定表名 '{tableName}' 的结构信息。

工具调用: 客户端可以调用 'execute-query' 工具来执行 SQL 查询，例如：

{
  "tool_call": {
    "name": "execute-query",
    "arguments": {
      "query": "SELECT COUNT(*) FROM {tableName}", //  替换 {tableName} 为实际表名
      "tableName": "{tableName}"                  //  指定要查询的表名，可选参数
    }
  }
}

Prompt 使用: 客户端可以获取预定义的 Prompt，例如 'analyze-data' 和 'generate-sql'，用于数据分析和 SQL 生成任务。

更多详细使用方法和高级配置，请参考仓库的 README.md 文件和源代码。

关键词