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.zip2. get_data
目的：检索解析的CSV数据供Claude分析
参数:
filename（字符串，必填）：要检索的CSV文件的名称sample_size（number，可选）：限制返回的行数
示例:
Get data from sales.csv with sample size 1003. list_loaded_data
目的：显示当前加载的CSV文件的信息
参数：无
示例:
List loaded data4. 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; // In-memory data cache
}主要职责:
- 初始化MCP服务器并注册工具
- 处理来自Claude Desktop的传入工具请求
- CSV解析器和zip处理程序之间的协调
- 管理内存中的数据缓存
2.CSV解析器(csv-parser.ts)
export class CSVParser {
async parseCSV(filePath: string): Promise
}主要特点:
- 标题标准化：将标头转换为带下划线的小写
- 数据类型检测：自动将字符串转换为数字、日期、布尔值
- 数据清理：删除空字符串，处理数字中的逗号
- 错误处理：继续处理时报告解析错误
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
}主要特点:
- 选择性萃取：仅从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服务器按原样提供，用于教育和开发目的。