File Analyzer

This guide will walk you through setting up a Model Context Protocol (MCP) server that can analyze CSV and Parquet files, and connecting it to Claude Desktop for natural language data analysis.

🎯 What You'll Build

A powerful data analysis tool that allows Claude to:

• 📊 Read and analyze CSV/Parquet files
• 📈 Generate statistical summaries
• 👀 Show data previews and structure
• 🔧 Create sample datasets
• 💬 Answer natural language questions about your data

Table of Contents

1. What is MCP?
2. Quick Start
3. Prerequisites
4. Project Setup
5. Claude Desktop Integration
6. Usage Examples
7. Testing & Verification
8. Troubleshooting
9. Extending the Server
10. Project Structure

What is MCP?

Model Context Protocol (MCP) is a standardized way to connect AI assistants like Claude to external tools and data sources. It allows you to:

• 🔐 Give Claude access to your local files (securely)
• 🛠️ Create custom tools that Claude can use
• 🔄 Build reusable AI workflows
• 🏠 Keep your data secure and local (no API keys needed!)

Quick Start

⚡ For the Impatient

# 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)

Prerequisites

Before you begin, make sure you have:

• Python 3.8 or higher installed
• pip (Python package manager)
• Claude Desktop installed (download here)
• macOS, Windows, or Linux (Claude Desktop support varies)

Check your Python version:

python3 --version  # Should be 3.8+

Project Setup

Step 1: Create Project and Virtual Environment

# 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

Step 2: Install Dependencies

Create 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

Install dependencies:

pip install -r requirements.txt

Step 3: Create Project Files

Your project needs these core files:

1. main.py - The MCP server
2. client.py - Testing client
3. requirements.txt - Dependencies
4. run_mcp_server.sh - Launcher script for Claude Desktop
5. claude_desktop_config.json - Claude Desktop configuration

Step 4: Create Helper Scripts

Create activate_env.sh for easy environment activation:

#!/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"

Make it executable:

chmod +x activate_env.sh

Claude Desktop Integration

🎯 Method 1: Direct Integration (Recommended)

Step 1: Create Launcher Script

Create 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

Make it executable:

chmod +x run_mcp_server.sh

Step 2: Create Claude Desktop Configuration

Create claude_desktop_config.json:

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

Important: Replace /ABSOLUTE/PATH/TO/YOUR/PROJECT with your actual project path. Get it with:

pwd  # Copy this output

Step 3: Install Configuration in Claude Desktop

Copy the configuration to Claude Desktop:

macOS:

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

Windows:

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

Linux:

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

Step 4: Restart Claude Desktop

1. Quit Claude Desktop completely
2. Relaunch the application
3. Look for the tool icon (🔨) in the interface

🌐 Method 2: HTTP Server (Alternative)

For web-based testing and debugging, you can also run an HTTP version:

# 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

Usage Examples

🚀 Getting Started with Claude

Once integrated, try these commands in Claude Desktop:

Basic Commands

Check available tools:

What MCP tools do you have available?

List data files:

What data files do I have available?

Analyze a CSV file:

Can you summarize the sample.csv file?

Advanced Analysis

Data exploration:

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

Statistical analysis:

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

Create new data:

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

Comprehensive analysis:

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

📊 Expected Results

Claude should respond with actual data from your files:

• File summaries: "CSV file 'sample.csv' has 5 rows and 4 columns. Columns: id, name, email, signup_date"
• Data previews: Formatted tables showing your actual data
• Statistical analysis: Mean, median, standard deviation for numeric columns
• Data insights: Observations about patterns in your data

🧪 Sample Data Included

Your MCP server automatically creates sample data:

sample.csv:

id,name,email,signup_date
1,Alice Johnson,[email protected],2023-01-15
2,Bob Smith,[email protected],2023-02-22
3,Carol Lee,[email protected],2023-03-10
4,David Wu,[email protected],2023-04-18
5,Eva Brown,[email protected],2023-05-30

Testing & Verification

🔧 Test the Server Directly

# Activate environment
source .venv/bin/activate

# Test server and client
python client.py

Expected output:

🚀 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...

🎮 Interactive Mode

python client.py interactive

Try these commands:

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

✅ Verify Claude Integration

In Claude Desktop, you should see:

1. Tool icon (🔨) in the interface
2. Available tools when you ask "What MCP tools do you have?"
3. Successful responses to data analysis questions

Troubleshooting

🐛 Common Issues

1. No Tool Icon in Claude Desktop

Symptoms: Claude Desktop starts but no MCP tools appear

Solutions:

# 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. "Server Not Found" Error

Symptoms: Claude shows error about server connection

Solutions:

# 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. "Module Not Found" Error

Symptoms: Import errors when starting server

Solutions:

# 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. Tools Appear But Don't Work

Symptoms: Tools listed but return errors

Solutions:

# 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

🔍 Debug Steps

1. Test each component independently:

   # Test server
   python main.py
   
   # Test client (in another terminal)
   python client.py
   
   # Test launcher
   ./run_mcp_server.sh
   

2. Check file permissions:

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

3. Validate configuration:

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

4. Check Claude Desktop logs:

   • Look for error messages in Claude Desktop
   • Check system logs for permission issues

Extending the Server

🛠️ Adding New Tools

Create custom tools with the @mcp.tool() decorator:

@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"

📚 Adding Resources

Provide static information to 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)

🔗 Adding Database Support

Connect to databases:

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()

Project Structure

Your complete project should look like this:

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

📁 Key Files Explained

• main.py: MCP server that provides file analysis tools
• client.py: Test client to verify server functionality
• run_mcp_server.sh: Launcher script for Claude Desktop integration
• claude_desktop_config.json: Configuration for Claude Desktop
• requirements.txt: Python package dependencies
• data/: Directory containing your data files

Next Steps

🚀 After Setup

1. Add your own data - Copy CSV/Parquet files to the data/ directory
2. Experiment with Claude - Try complex data analysis questions
3. Create custom tools - Build tools specific to your workflow
4. Explore advanced features - Add database connections, web APIs, etc.

💡 Ideas for Enhancement

• Excel support - Add tools for .xlsx files
• Data visualization - Generate charts and graphs
• Database integration - Connect to SQL databases
• API connections - Fetch data from web APIs
• Machine learning - Add prediction and analysis tools
• File monitoring - Watch directories for new data files

🔗 Useful Resources

• MCP Documentation
• MCP Python SDK
• Claude Desktop
• Pandas Documentation

---

Claude Desktop Integration

To use this MCP server from Claude Desktop (macOS):

1. Make the launcher script executable:

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

Natural Language Interaction Testing with Claude Desktop

1. File listing

   • Prompt:
     “Please list all available data files from the file_analyzer MCP server.”

   • Behavior:
     Claude called the list_data_files tool and returned the same set of files as the Python client:

     client_generated.csv, generated_test.csv, sample.csv, sample.parquet.

2. CSV summarization

   • Prompt:
     “Summarize the structure of sample.csv (row count, column count, column names, and data types).”

   • Behavior:
     Claude invoked summarize_csv_file with {"filename": "sample.csv"} and replied that the file has 5 rows and 4 columns (id, name, email, signup_date) with dtypes matching the pandas output: id → int64, the others → object.
     This matches exactly what I see when running python client.py.

3. Data analysis (describe / head / info)

   • Prompts (asked in separate turns):

     “Run a describe analysis on sample.csv.”
     “Show me the first 5 rows of sample.csv.”
     “Give me the pandas info summary for sample.csv.”

   • Behavior:
     Claude mapped these to analyze_csv_data with operation="describe", "head", and "info" respectively.
     The numeric summary for id (count 5, mean 3, std ≈ 1.58, min 1, max 5) and the printed head/info are the same as the outputs from the interactive Python client.

4. Data creation

   • Prompt:
     “Create a new sample CSV called new_sample.csv with 5 rows of data.”

   • Behavior:
     Claude used create_sample_data with {"filename": "new_sample.csv", "rows": 5} and confirmed that the file was created under the data/ directory. The path and row count match what I see on disk and in the command-line client.

5. Error handling / edge cases

   • Prompts:

     “Summarize a CSV file named missing.csv.”
     “Analyze sample.csv without specifying the operation.”

   • Behavior:
     For the missing file, Claude surfaced the server’s error message:

     Error: CSV file 'missing.csv' does not exist in data directory.

     For the incomplete analyze command, it reported the usage hint
     (analyze <filename> <operation>) and listed the supported operations (describe, head, info, columns).
     This matches the edge-case behavior tested in test.py.

3. Performance Analysis and Comparison

3.1 Response time: direct client vs. Claude Desktop

For simple operations on the small sample dataset (5 rows, 4 columns), the direct Python client (python client.py / python test.py) returns almost instantly – typically within a fraction of a second for:

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

When the same operations are triggered via Claude Desktop, there is a small but noticeable overhead. Claude has to:

1. parse the user’s natural-language request,
2. decide which MCP tool to call and with which arguments,
3. send the request over the MCP stdio connection, and
4. render the response back into a chat-style answer.

In practice this adds a few hundred milliseconds to around a second, depending on the complexity of the prompt and Claude’s own model latency. Because all file I/O and pandas work happen locally, the extra delay is dominated by the LLM and message-passing overhead, not by the MCP server itself.

3.2 Natural language vs. programmatic tool invocation

Programmatic calls (via client.py or the automated tests in test.py) are:

• Deterministic – arguments are explicit (filename, operation),
• Strictly validated – the client prints usage errors such as
  Usage: analyze <filename> <operation> when the user forgets an argument,
• Easy to automate – suitable for CI or regression tests.

Natural-language use through Claude Desktop is more flexible but also a bit less predictable:

• It is much easier for a non-technical user to type
  “Summarize the structure of sample.csv”
  than to remember the exact CLI syntax.
• However, ambiguous prompts can lead to small misunderstandings. For example, a request like “summarize file” does not specify the extension, and the server correctly responds with an error asking for “.csv or .parquet”.
• For well-phrased prompts, Claude reliably maps questions to the right tools (list_data_files, summarize_csv_file, analyze_csv_data, etc.), and the outputs line up with what the Python client shows.

3.3 User experience and practical applications

From a user-experience perspective:

• The Python client is ideal for developers: it exposes exact tool names, arguments, and raw outputs (JSON or plain tables).
• The Claude integration is better for “conversational” analysis:
  • A user can ask a high-level question (e.g., “What does this CSV look like? Any obvious patterns?”), and Claude will combine MCP tool results with its own narrative explanation.
  • Multi-step interactions like “list files → pick a file → show head → describe columns” feel natural inside a chat thread.

In a real-world workflow, a typical pattern would be:

1. Use Claude + MCP for initial exploration and quick questions.
2. Switch to direct Python or notebooks when building more complex pipelines or when results need to be scripted and version-controlled.

3.4 Limitations and potential improvements

A few limitations of the current system and ideas for improvement:

• Dataset size: the tools assume relatively small CSV/Parquet files that fit in memory. For larger datasets, the server would need chunked reading, sampling, or out-of-core processing.
• Limited operations: current tools focus on listing files, summarization, and basic pandas analysis. In the future, it would be useful to add:
  • filtering and simple query tools,
  • group-by/aggregation helpers,
  • basic visualization (e.g., histograms or scatter plots exported as files).
• Error reporting: error messages are clear but minimal. More structured error codes and suggestions (e.g., “did you mean sample.csv?”) could make the Claude interaction smoother.
• Claude integration robustness: on some runs, Claude Desktop logs show unrelated CSP/UI warnings. Although the MCP server and Python clients work correctly, the integration could be hardened by:
  • adding more logging around MCP startup and shutdown,
  • providing clearer instructions for regenerating the config and troubleshooting local desktop issues.

🎉 Congratulations!

You now have a fully functional MCP server that can:

✅ Analyze CSV and Parquet files
✅ Respond to natural language queries through Claude
✅ Create and manipulate data files
✅ Provide detailed statistical analysis
✅ Work entirely offline (no API keys required!)

Happy data analyzing! 📊🤖