使用说明

CSV查询MCP服务器文档

概述

CSV查询MCP服务器是一个定制的模型上下文协议（MCP）服务器，旨在加载、解析和分析CSV数据文件。它使Claude Desktop能够处理来自zip文件和目录的CSV数据，提供结构化数据分析功能。

特性

Zip文件支持：自动从zip存档中提取CSV文件
智能CSV解析：将CSV数据转换为结构化JSON对象
数据类型检测：自动转换数字、日期和布尔值
标题标准化：清理并标准化列标题
内存缓存：一次加载数据并允许多次查询
错误处理：强大的错误报告和验证

建筑

MCP服务器由三个主要组件组成：

┌─────────────────┐    ┌─────────────────┐    ┌─────────────────┐
│   Claude        │    │   MCP Server    │    │   File System   │
│   Desktop       │◄──►│   (Node.js)     │◄──►│   CSV/Zip Files │
└─────────────────┘    └─────────────────┘    └─────────────────┘

数据流

负载：用户请求从zip或目录加载CSV文件
提取：提取Zip文件，识别CSV文件
解析：CSV文件被解析为结构化JSON对象
缓存：解析后的数据存储在内存中，以便快速访问
查询：Claude请求数据并直接分析

安装

先决条件

Node.js 18+
克劳德桌面
TypeScript

设置步骤

创建项目目录
```
mkdir csv-query-mcp
cd csv-query-mcp
```
再进行
```
npm install
```
生成项目
```
npm run build
```
配置Claude桌面

编辑您的Claude Desktop配置文件：
- 视窗: %APPDATA%\Claude\claude_desktop_config.json
- macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
```
{
  "mcpServers": {
    "csv-query": {
      "command": "node",
      "args": ["/path/to/csv-query-mcp/build/index.js"]
    }
  }
}
```
重新启动克劳德桌面

配置

package.json

{
  "name": "csv-query-mcp",
  "type": "module",
  "dependencies": {
    "@modelcontextprotocol/sdk": "^0.5.0",
    "papaparse": "^5.4.1",
    "lodash": "^4.17.21",
    "yauzl": "^2.10.0"
  }
}

配置要点：

"type": "module" 启用ES6模块语法
MCP SDK处理与Claude Desktop的通信
Papa Parse提供强大的CSV解析
Yauzl处理zip文件提取

可用工具

1. `load_csv_files`

目的：从zip存档或目录加载CSV文件

参数:

source （字符串，必填）：包含CSV的zip文件或目录的路径

示例:

Load CSV files from C:/data/sales_data.zip

2. `get_data`

目的：检索解析的CSV数据供Claude分析

参数:

filename （字符串，必填）：要检索的CSV文件的名称
sample_size （number，可选）：限制返回的行数

示例:

Get data from sales.csv with sample size 100

3. `list_loaded_data`

目的：显示当前加载的CSV文件的信息

参数：无

示例:

List loaded data

4. `preview_data`

目的：显示CSV文件结构的快速预览

参数:

filename （字符串，必填）：要预览的CSV文件的名称
rows （number，可选）：要显示的行数（默认值：5）

示例:

Preview data from customers.csv showing 10 rows

编码结构

文件组织

csv-query-mcp/
├── src/
│   ├── index.ts          # Main MCP server and tool handlers
│   ├── csv-parser.ts     # CSV parsing logic with Papa Parse
│   └── zip-handler.ts    # Zip file extraction utilities
├── build/                # Compiled JavaScript (auto-generated)
├── package.json          # Dependencies and scripts
└── tsconfig.json         # TypeScript configuration

核心组件

1.主服务器(`index.ts`)

class CSVQueryMCPServer {
  private server: Server;                    // MCP server instance
  private csvParser: CSVParser;              // CSV parsing component
  private zipHandler: ZipHandler;            // Zip extraction component
  private loadedData: Map<string, any[]>;    // In-memory data cache
}

主要职责:

初始化MCP服务器并注册工具
处理来自Claude Desktop的传入工具请求
CSV解析器和zip处理程序之间的协调
管理内存中的数据缓存

2.CSV解析器(`csv-parser.ts`)

export class CSVParser {
  async parseCSV(filePath: string): Promise<any[]>
}

主要特点:

标题标准化：将标头转换为带下划线的小写
数据类型检测：自动将字符串转换为数字、日期、布尔值
数据清理：删除空字符串，处理数字中的逗号
错误处理：继续处理时报告解析错误

Papa解析配置:

Papa.parse(fileContent, {
  header: true,           // Use first row as object keys
  skipEmptyLines: true,   // Ignore blank rows
  dynamicTyping: true,    // Auto-convert data types
  transformHeader: ...,   // Clean header names
  transform: ...          // Clean data values
});

3.拉链处理器(`zip-handler.ts`)

export class ZipHandler {
  async extractZip(zipPath: string, extractPath: string): Promise<string[]>
}

主要特点:

选择性萃取：仅从zip存档中提取CSV文件
目录创建：自动创建提取目录
文件路径管理：返回提取的CSV文件的完整路径
错误处理：提供zip问题的详细错误消息

数据转换管道

原始CSV输入:

City,Receipts,Revenue
New York,100,5000
Los Angeles,80,4200

Papa解析处理:
- 标头已标准化： city, receipts, revenue
- 转换的数字： "100" → 100
- 创建的结构：对象数组

最终JSON输出:

[
  {"city": "New York", "receipts": 100, "revenue": 5000},
  {"city": "Los Angeles", "receipts": 80, "revenue": 4200}
]

克劳德分析：接收结构化数据以进行直接分析

使用示例

基本工作流程

加载数据:
```
Load CSV files from C:/data/Q1_sales.zip
```
服务器提取zip，解析CSV，缓存数据
探索结构:
```
List loaded data
```
显示：sales.cv:1247行，8列[日期、客户、产品、金额、城市…]
预览数据:
```
Preview data from sales.csv
```
显示具有列结构的前5行
提出问题:
```
What city generated the most revenue?
```
Claude自动使用get_data工具进行分析

高级分析示例

销售分析:

- Which month had the highest sales?
- What's the average order value by region?
- Show me the top 10 customers by total purchases
- Are there any seasonal trends in the data?

数据质量检查:

- Are there any duplicate customer IDs?
- What percentage of orders have missing data?
- Which products have unusual pricing?

比较分析:

- How does Q1 compare to Q4 performance?
- Which sales rep has the best conversion rate?
- What's the geographic distribution of our customers?

故障排除

常见问题

1.“引用错误：未定义需求”

原因：混合CommonJS和ES模块语法 解决方案：确保所有导入都使用ES6语法：

// ✅ Correct
import { createWriteStream } from 'fs';

// ❌ Incorrect  
const fs = require('fs');

2.“服务器意外断开连接”

原因：服务器代码中的运行时错误 解决方案:

手动测试服务器： node build/index.js
检查控制台以了解错误详细信息
验证文件路径是否正确

3.“当前未加载CSV文件”

原因：加载操作失败或路径不正确 解决方案:

验证文件路径是否存在
检查文件权限
确保zip包含CSV文件

4.“解析CSV文件失败”

原因：CSV格式错误或编码问题 解决方案:

检查CSV文件格式
验证文件编码（应为UTF-8）
查找特殊字符或损坏的数据

调试步骤

检查MCP服务器状态:

node build/index.js
# Should show: "CSV Query MCP server running on stdio"

验证配置:
- 检查 claude_desktop_config.json 语法
- 确保文件路径使用正斜杠或转义反斜杠
- 配置更改后重新启动Claude Desktop
使用简单数据进行测试: 创建一个简单的测试CSV：
```
name,age,city
John,25,NYC
Jane,30,LA
```
检查克劳德桌面日志:
- Help → 开发者工具→ 控制台
- 查找与MCP相关的错误消息

性能注意事项

大文件：使用 sample_size 初步勘探参数
内存使用：服务器将所有数据保存在内存中-需要时重新启动
文件大小限制：没有硬限制，但非常大的文件可能会导致速度减慢

高级功能

自定义数据转换

CSV解析器包括几个内置的转换：

日期检测：识别常见的日期格式（YYYY-MM-DD、MM/DD/YYYY）
数字解析：处理带逗号的数字（1000→1000）
布尔识别：将“true”/“false”字符串转换为布尔值
空处理：空字符串变为空值

错误恢复

服务器包括全面的错误处理：

部分加载成功：如果某些CSV失败，其他CSV仍会加载
故障弱化：服务器在出错后继续运行
详细错误消息：清楚地描述出了什么问题

未来的增强功能

未来版本的潜在改进：

数据库集成：将解析后的数据存储在SQLite中以实现持久化
Google Drive集成：直接访问Google Drive文件
数据验证：模式验证和数据质量检查
导出功能：将分析结果保存到文件
流媒体支持：使用流媒体处理非常大的文件

贡献

要修改或扩展服务器，请执行以下操作：

发展模式:

npm run dev  # Watches for changes and rebuilds

添加新工具：扩展 setupToolHandlers() 方法
自定义分析器：修改 csv-parser.ts 对于特定的数据格式
其他文件类型：扩展 zip-handler.ts 其他档案

许可证

此MCP服务器按原样提供，用于教育和开发目的。

使用说明

CSV查询MCP服务器文档

概述

目录

特性

建筑

数据流

安装

先决条件

设置步骤

配置

package.json

可用工具

1. load_csv_files

2. get_data

3. list_loaded_data

4. preview_data