使用说明

MCP文件分析器：完整的安装和使用指南

本指南将引导您设置一个可以分析CSV和Parquet文件的模型上下文协议（MCP）服务器，并将其连接到Claude Desktop进行自然语言数据分析。

🎯 你将建造什么

一个强大的数据分析工具，使克劳德能够：

📊 读取和分析CSV/Parquet文件
📈 生成统计摘要
👀 显示数据预览和结构
🔧 创建示例数据集
💬 回答有关数据的自然语言问题

什么是MCP？

模型上下文协议（MCP）是一种将Claude等人工智能助手连接到外部工具和数据源的标准化方法。它允许您：

🔐 让Claude访问您的本地文件（安全）
🛠️ 创建Claude可以使用的自定义工具
🔄 构建可重用的AI工作流程
🏠 保持您的数据安全和本地（不需要API密钥！）

快速开始

⚡ 对于不耐烦的人

# Clone or create project directory
mkdir mcp-file-analyzer && cd mcp-file-analyzer

# Set up virtual environment
python3 -m venv .venv && source .venv/bin/activate

# Install dependencies
pip install mcp>=1.0.0 pandas>=2.0.0 pyarrow>=10.0.0

# Create and test the server (copy main.py and client.py from this repo)
python main.py  # Start server (Ctrl+C to stop)
python client.py  # Test the connection

# Configure Claude Desktop (see detailed steps below)

先决条件

在开始之前，请确保您已经：

Python 3.8或更高版本 安装
点（Python包管理器）
克劳德桌面版 已安装(在这里下载)
macOS、Windows或Linux （克劳德桌面支持各不相同）

检查你的Python版本：

python3 --version  # Should be 3.8+

项目设置

步骤1：创建项目和虚拟环境

# Create project directory
mkdir mcp-file-analyzer
cd mcp-file-analyzer

# Create virtual environment
python3 -m venv .venv

# Activate virtual environment
# On macOS/Linux:
source .venv/bin/activate
# On Windows:
.venv\Scripts\activate

步骤2：安装依赖项

创建 requirements.txt:

# Core dependencies for MCP File Analyzer
mcp>=1.0.0
pandas>=2.0.0
pyarrow>=10.0.0

# HTTP client dependencies (optional)
httpx>=0.27.0

# Development dependencies (optional)
# pytest>=7.0.0
# black>=23.0.0
# flake8>=6.0.0

安装依赖项：

pip install -r requirements.txt

步骤3：创建项目文件

您的项目需要以下核心文件：

main.py -MCP服务器
客户端.py -测试客户端
需求.txt -依赖关系
run_mcp_server.sh -Claude Desktop的启动脚本
claude_desktop_config json -Claude桌面配置

步骤4：创建辅助脚本

创建 activate_env.sh 为了便于环境激活：

#!/bin/bash
echo "🚀 Activating virtual environment..."
source .venv/bin/activate
echo "✅ Virtual environment activated!"
echo "📦 Installed packages:"
pip list --format=columns
echo ""
echo "🎯 Quick start commands:"
echo "  - Run MCP server: python main.py"
echo "  - Run demo client: python client.py"
echo "  - Interactive client: python client.py interactive"

使其可执行：

chmod +x activate_env.sh

Claude桌面集成

🎯 方法1：直接集成（推荐）

步骤1：创建启动器脚本

创建 run_mcp_server.sh:

#!/bin/bash
# MCP Server Launcher for Claude Desktop

# Get the directory where this script is located
SCRIPT_DIR="$( cd "$( dirname "${BASH_SOURCE[0]}" )" &> /dev/null && pwd )"

# Change to the script directory
cd "$SCRIPT_DIR"

# Activate the virtual environment
source .venv/bin/activate

# Run the MCP server
python main.py

使其可执行：

chmod +x run_mcp_server.sh

步骤2：创建Claude桌面配置

创建 claude_desktop_config.json:

{
  "mcpServers": {
    "file_analyzer": {
      "command": "/ABSOLUTE/PATH/TO/YOUR/PROJECT/run_mcp_server.sh",
      "args": []
    }
  }
}

重要提示： 替换 /ABSOLUTE/PATH/TO/YOUR/PROJECT 根据您的实际项目路径。用以下方式获取：

pwd  # Copy this output

步骤3：在Claude Desktop中安装配置

将配置复制到Claude Desktop：

macOS：

cp claude_desktop_config.json ~/Library/Application\ Support/Claude/claude_desktop_config.json

窗户：

copy claude_desktop_config.json %APPDATA%\Claude\claude_desktop_config.json

Linux：

cp claude_desktop_config.json ~/.config/claude/claude_desktop_config.json

步骤4:重新启动克劳德桌面

完全退出克劳德桌面
重新启动应用程序
查找工具图标(🔨) 在界面中

🌐 方法2:HTTP服务器（可选）

对于基于web的测试和调试，您还可以运行HTTP版本：

# Install additional dependencies
pip install uvicorn fastapi

# Start HTTP server
python http_server.py

# Test with HTTP client
python http_client.py

# Access web interface
open http://localhost:8000/docs

使用示例

🚀 克劳德入门

集成后，在Claude Desktop中尝试以下命令：

基本命令

检查可用工具：

What MCP tools do you have available?

列出数据文件：

What data files do I have available?

分析CSV文件：

Can you summarize the sample.csv file?

高级分析

数据探索：

Show me the first 5 rows of sample.csv and tell me about the data structure

统计分析：

Give me statistical information about sample.csv - what are the data types and any interesting patterns?

创建新数据：

Create a new CSV file called "customer_data.csv" with 50 rows of sample customer data

综合分析：

List all my data files, pick the most interesting one, and give me a complete analysis including:
- File structure and dimensions
- Data types for each column  
- First few rows as examples
- Statistical summary for numeric columns

📊 预期结果

Claude应该用你文件中的实际数据来回应：

文件摘要： CSV文件“sample.CSV”有5行4列。列：id、name、email、signup_date
数据预览： 显示实际数据的格式化表格
统计分析： 数值列的平均值、中位数、标准偏差
数据洞察： 对数据中模式的观察

🧪 包含样本数据

您的MCP服务器会自动创建示例数据：

sample.csv：

id,name,email,signup_date
1,Alice Johnson,alice@example.com,2023-01-15
2,Bob Smith,bob@example.com,2023-02-22
3,Carol Lee,carol@example.com,2023-03-10
4,David Wu,david@example.com,2023-04-18
5,Eva Brown,eva@example.com,2023-05-30

测试与验证

🔧 直接测试服务器

# Activate environment
source .venv/bin/activate

# Test server and client
python client.py

预期产量：

🚀 Starting MCP File Analyzer Client Demo
==================================================
✅ Connected to MCP server successfully!

🔧 Available tools:
  - list_data_files
  - summarize_csv_file
  - summarize_parquet_file
  - analyze_csv_data
  - create_sample_data

📂 Listing data files:
📄 Result: Available data files: sample.csv, sample.parquet

📊 Summarizing CSV file:
📄 Result: CSV file 'sample.csv' has 5 rows and 4 columns...

🎮 交互模式

python client.py interactive

尝试以下命令：

list_files
summarize sample.csv
analyze sample.csv head
create test_data.csv 10

✅ 验证Claude集成

在Claude Desktop中，您应该看到：

工具图标(🔨) 在界面中
可用工具 当你问“你有什么MCP工具？”
成功响应 数据分析问题

故障排除

🐛 常见问题

1.克劳德桌面中没有工具图标

症状： Claude Desktop启动，但未显示MCP工具

解决：

# Check config file location
ls -la ~/Library/Application\ Support/Claude/claude_desktop_config.json

# Verify JSON syntax
cat ~/Library/Application\ Support/Claude/claude_desktop_config.json

# Test launcher script
./run_mcp_server.sh

# Check permissions
chmod +x run_mcp_server.sh

2.“找不到服务器”错误

症状： Claude显示服务器连接错误

解决：

# Verify absolute path in config
pwd  # Make sure this matches your config

# Test server independently
source .venv/bin/activate
python main.py

# Check virtual environment
which python  # Should show .venv path

3.“找不到模块”错误

症状： 启动服务器时导入错误

解决：

# Reinstall dependencies
source .venv/bin/activate
pip install -r requirements.txt

# Verify installation
pip list | grep mcp
pip list | grep pandas
pip list | grep pyarrow

4.工具出现但不起作用

症状： 列出了工具，但返回了错误

解决：

# Check data directory
ls -la data/

# Recreate sample data
rm -rf data/
python main.py  # Will recreate sample files

# Test with client
python client.py

🔍 调试步骤

独立测试每个组件：

# Test server
python main.py

# Test client (in another terminal)
python client.py

# Test launcher
./run_mcp_server.sh

检查文件权限：

ls -la *.py *.sh
chmod +x run_mcp_server.sh

验证配置：

# Check JSON syntax
python -c "import json; print(json.load(open('claude_desktop_config.json')))"

检查克劳德桌面日志：
- 在Claude Desktop中查找错误消息
- 检查系统日志是否存在权限问题

扩展服务器

🛠️ 添加新工具

使用创建自定义工具 @mcp.tool() 装饰师：

@mcp.tool()
def analyze_excel_file(filename: str) -> str:
    """
    Analyze an Excel file and return summary information.
    Args:
        filename: Name of the Excel file (e.g., 'data.xlsx')
    Returns:
        A string describing the file's contents.
    """
    import pandas as pd
    file_path = DATA_DIR / filename
    
    # Read Excel file
    df = pd.read_excel(file_path)
    
    return f"Excel file '{filename}' has {len(df)} rows and {len(df.columns)} columns"

📚 添加资源

向Claude提供静态信息：

@mcp.resource("data://file-formats")
def get_supported_formats() -> str:
    """List supported file formats."""
    formats = {
        "supported_formats": ["CSV", "Parquet", "Excel", "JSON"],
        "max_file_size": "100MB",
        "encoding": "UTF-8"
    }
    return json.dumps(formats, indent=2)

🔗 添加数据库支持

连接到数据库：

import sqlite3

@mcp.tool()
def query_database(query: str) -> str:
    """
    Execute a SQL query on the local database.
    Args:
        query: SQL query to execute
    Returns:
        Query results as formatted text.
    """
    conn = sqlite3.connect('data/database.db')
    df = pd.read_sql_query(query, conn)
    conn.close()
    
    return df.to_string()

项目结构

你的完整项目应该是这样的：

mcp-file-analyzer/
├── .venv/                          # Virtual environment
├── data/                           # Data files (auto-created)
│   ├── sample.csv                  # Sample CSV data
│   ├── sample.parquet              # Sample Parquet data
│   └── ...                        # Your data files
├── main.py                         # MCP server (stdio)
├── client.py                       # Test client (stdio)
├── http_server.py                  # HTTP MCP server (optional)
├── http_client.py                  # HTTP test client (optional)
├── requirements.txt                # Python dependencies
├── activate_env.sh                 # Environment activation script
├── run_mcp_server.sh              # Claude Desktop launcher
├── claude_desktop_config.json     # Claude Desktop config
├── .gitignore                     # Git ignore file
└── README.md                      # This file

📁 关键文件说明

main.py：提供文件分析工具的MCP服务器
客户端.py：测试客户端以验证服务器功能
run_mcp_server.sh：用于Claude Desktop集成的启动器脚本
claude_desktop_config json：克劳德桌面配置
需求.txt：Python包依赖关系
数据/：包含数据文件的目录

后续步骤

🚀 安装后

添加您自己的数据 -将CSV/Parquet文件复制到 data/ 目录
克劳德实验 -尝试复杂的数据分析问题
创建自定义工具 -构建特定于您工作流程的工具
探索高级功能 -添加数据库连接、web API等。

💡 增强的想法

Excel支持 -为.xlsx文件添加工具
数据可视化 -生成图表和图形
数据库集成 -连接到SQL数据库
API连接 -从web API获取数据
机器学习 -添加预测和分析工具
文件监控 -监视新数据文件的目录

🔗 有用的资源

Claude桌面集成

要从Claude Desktop（macOS）使用此MCP服务器，请执行以下操作：

使启动器脚本可执行：

chmod +x /Users/gaohan/Downloads/file_analyzer-main/run_mcp_server.sh

使用Claude Desktop进行自然语言交互测试

文件列表
- 提示：
  “请列出 file_analyzer MCP服务器。”
- 行为：
  克劳德打电话给 list_data_files 工具并返回了相同的文件集作为Python客户端：
  
  client_generated.csv, generated_test.csv, sample.csv, sample.parquet.
CSV摘要
- 提示：
  “总结结构 sample.csv （行数、列数、列名称和数据类型）。”
- 行为：
  克劳德调用 summarize_csv_file 和 {"filename": "sample.csv"} 和已回复该文件 5行和 4列 (id, name, email, signup_date)dtypes与pandas匹配输出： id → int64，其他→ object.
  这与我跑步时看到的完全吻合 python client.py.
数据分析（描述/头部/信息）
- 提示（分别提问）：
  
  “跑a 描述分析 sample.csv.”
  “给我看前5行 sample.csv.”
  “把熊猫给我信息总结 sample.csv.”
- 行为：
  克劳德将这些映射到 analyze_csv_data 和 operation="describe", "head"，以及 "info" 分别。
  的数字摘要 id （计数5，平均值3，标准差≈1.58，最小值1，最大值5）打印的头部/信息与交互式输出相同 Python客户端。
数据创建
- 提示：
  “创建一个名为CSV的新示例 new_sample.csv 有5行数据。”
- 行为：
  克劳德使用 create_sample_data 和 {"filename": "new_sample.csv", "rows": 5} 并确认该文件是在 data/ 目录。路径和行数与我在磁盘和命令行客户端。
错误处理/边缘情况
- 提示：
  
  “总结一个名为 missing.csv.”
  “分析 sample.csv 而不指定操作。”
- 行为：
  对于丢失的文件，Claude显示了服务器的错误消息：
  
  Error: CSV file 'missing.csv' does not exist in data directory.
  
  对于不完整的分析命令，它报告了使用提示
  (analyze <filename> <operation>)并列出了支持的操作 (describe, head, info, columns).
  这与中测试的边缘情况行为相匹配 test.py.

3.性能分析与比较

3.1响应时间：直接客户端与Claude Desktop

用于对小样本数据集进行简单操作(5 排， 4 列）直接Python客户端(python client.py / python test.py)几乎返回瞬间——通常在几分之一秒内：

list_data_files
summarize_csv_file("sample.csv")
analyze_csv_data("sample.csv", "head" | "info" | "describe")
create_sample_data(..., rows=5)

当通过Claude Desktop触发相同的操作时，会有一个小但明显的开销。克劳德必须：

解析用户的自然语言请求，
决定调用哪个MCP工具以及使用哪些参数，
通过MCP stdio连接发送请求，以及
将响应还原为聊天风格的答案。

在实践中，这会增加几百毫秒到大约一秒，具体取决于提示的复杂性和Claude自己的模型延迟。因为所有文件I/O和pandas工作发生在本地，额外的延迟主要由 LLM和消息传递开销，而不是MCP服务器本身。

3.2自然语言与程序化工具调用

程序化调用（通过 client.py 或自动化测试 test.py)它们是：

确定性的 –参数是明确的(filename, operation),
严格验证 –客户端打印使用错误，例如
Usage: analyze <filename> <operation> 当用户忘记一个论点时，
易于自动化 –适用于CI或回归测试。

通过Claude Desktop使用自然语言更灵活，但也有点不太可预测：

对于非技术用户来说，键入要容易得多
“总结结构 sample.csv”
而不是记住确切的CLI语法。
然而，模棱两可的提示可能会导致小的误解。例如，像“summary file”这样的请求没有指定扩展名服务器正确地响应了一个错误，要求输入“.csv或.plack”。
对于措辞得当的提示，Claude可靠地将问题映射到正确的工具上 (list_data_files, summarize_csv_file, analyze_csv_data等），以及输出与Python客户端显示的一致。

3.3用户体验和实际应用

从用户体验的角度来看：

这 Python客户端 非常适合开发人员：它公开了确切的工具名称，参数和原始输出（JSON或纯表）。
这 克劳德整合 更适合“对话式”分析：
- 用户可以问一个高级问题（例如。， “这个CSV是什么样子的？有明显的模式吗？”)，Claude将把MCP工具的结果与其自己的叙事解释。
- 多步交互，如“列表文件”→ 选取一个文件→ 显示头部→ 描述列“在聊天线程中感觉很自然。

在现实世界的工作流程中，典型的模式是：

使用Claude+MCP进行初步探索和快速提问。
构建更复杂的管道时，切换到直接Python或笔记本电脑或者当需要编写脚本和版本控制结果时。

3.4局限性和潜在改进

当前系统的一些局限性和改进思路：

数据集大小：这些工具假设相对较小的CSV/Parquet文件适合记忆。对于较大的数据集，服务器需要分块读取，例如采样或芯外处理。
有限的运营：当前的工具侧重于列出文件、摘要、，以及基本的熊猫分析。今后，添加以下内容将是有益的：
- 过滤和简单的查询工具，
- 分组/聚合助手，
- 基本可视化（例如导出为文件的直方图或散点图）。
错误报告：错误消息很清楚，但很小。更有条理错误代码和建议（例如，“你是说 sample.csv“）可以使克劳德的互动更加顺畅。
Claude集成稳健性：在某些运行中，Claude Desktop日志显示不相关的CSP/UI警告。虽然MCP服务器和Python客户端可以工作正确地说，可以通过以下方式加强集成：
- 在MCP启动和关闭时添加更多日志记录，
- 为重新生成配置提供更清晰的说明解决本地桌面问题。

🎉 祝贺

您现在拥有一个功能齐全的MCP服务器，可以：

✅ 分析CSV和Parquet文件
✅ 通过Claude回复自然语言查询
✅ 创建和操作数据文件
✅ 提供详细的统计分析
✅ 完全脱机工作（不需要API密钥！）

数据分析愉快！ 📊🤖

使用说明

MCP文件分析器：完整的安装和使用指南

🎯 你将建造什么

目录

什么是MCP？

快速开始

⚡ 对于不耐烦的人

先决条件

项目设置

步骤1：创建项目和虚拟环境

步骤2：安装依赖项

步骤3：创建项目文件

步骤4：创建辅助脚本

Claude桌面集成

🎯 方法1：直接集成（推荐）

步骤1：创建启动器脚本

步骤2：创建Claude桌面配置

步骤3：在Claude Desktop中安装配置

步骤4:重新启动克劳德桌面

🌐 方法2:HTTP服务器（可选）

使用示例

🚀 克劳德入门

基本命令

高级分析

📊 预期结果

🧪 包含样本数据

测试与验证

🔧 直接测试服务器

🎮 交互模式

✅ 验证Claude集成

故障排除

🐛 常见问题

1.克劳德桌面中没有工具图标

2.“找不到服务器”错误

3.“找不到模块”错误

4.工具出现但不起作用

🔍 调试步骤

扩展服务器

🛠️ 添加新工具

📚 添加资源

🔗 添加数据库支持

项目结构

📁 关键文件说明

后续步骤

🚀 安装后

💡 增强的想法

🔗 有用的资源

Claude桌面集成

使用Claude Desktop进行自然语言交互测试

3.性能分析与比较

3.1响应时间：直接客户端与Claude Desktop

3.2自然语言与程序化工具调用

3.3用户体验和实际应用

3.4局限性和潜在改进

🎉 祝贺

相关 MCP

文件与终端管理MCP服务

图表生成MCP服务器

Flomo笔记服务

ECharts 图表生成 MCP 服务

图表生成服务

Excel文件管理分析服务