CSV MCP Server

A Model Context Protocol (MCP) server that provides AI assistants with powerful CSV file operations. This server enables natural language interactions with CSV data through comprehensive reading, writing, querying, transformation, and analysis tools.

🚀 Quick Install

NPX (Recommended - No Installation Required)

# Setup CSV MCP in Claude Desktop (no configuration needed!)
npx csv-mcp init

# Check status
npx csv-mcp status

Global Installation

# Install globally for repeated use
npm install -g csv-mcp
csv-mcp init
csv-mcp status

Restart Claude Desktop after setup.

✨ New: Use with NPX - no installation required! Just run npx csv-mcp init once.

💡 No directory configuration needed! Simply specify CSV file paths naturally in your requests:

• "Read /path/to/data.csv"
• "Analyze ~/Documents/sales.csv"
• "Query ./data/customers.csv where age > 30"

✨ Features

📁 CSV File Operations

• Read CSV files - Load and parse CSV data with various options
• Write CSV files - Create new CSV files or overwrite existing ones
• Append data - Add rows to existing CSV files
• File information - Get metadata about CSV files

🔍 Powerful Querying

• SELECT columns - Choose specific columns to retrieve
• WHERE clauses - Filter rows with complex conditions
• ORDER BY - Sort data by multiple columns
• LIMIT & OFFSET - Paginate through large datasets
• DISTINCT - Get unique rows only

🔧 Data Transformation

• Add columns - Create new columns with computed values
• Remove columns - Delete unnecessary columns
• Rename columns - Change column names
• Transform values - Apply functions to transform data
• Filter rows - Remove rows based on conditions

📊 Data Analysis

• Statistics - Get min, max, mean, median, mode, standard deviation
• Column analysis - Analyze individual columns
• Data type detection - Automatic type inference
• Top values - Find most common values
• Null counts - Track missing data
• Unique counts - Count distinct values

🔗 Advanced Operations

• Merge CSV files - Join two CSV files (inner, left, right, outer joins)
• Aggregate data - GROUP BY with SUM, AVG, COUNT, MIN, MAX
• Search - Full-text search across columns
• Export - Convert to different formats

🛠️ Installation

Prerequisites

• Node.js (v16 or higher)
• Claude Desktop or any MCP-compatible AI client

Quick Setup (NPX - Recommended)

1. Run the init command:

   npx csv-mcp init

2. Restart Claude Desktop and you're ready!

3. Start using it naturally:

   • "Read /Users/john/data.csv"
   • "Analyze ~/Documents/sales-2024.csv"
   • "Query ./customers.csv where age > 30"

Alternative Installation Methods

Install globally:

npm install -g csv-mcp
csv-mcp init

Use from source:

git clone https://github.com/nitaiaharoni1/csv-mcp.git
cd csv-mcp
npm install
npm run build

🎯 Available Tools

The CSV MCP server provides 18 powerful tools for CSV operations:

File Operations

• read_csv - Read a CSV file and return its contents
• write_csv - Write data to a CSV file
• append_csv - Append rows to an existing CSV file
• get_csv_info - Get information about a CSV file

Query & Filter

• query_csv - Query CSV with SQL-like operations (SELECT, WHERE, ORDER BY, LIMIT)
• search_csv - Search for text across columns

Transformation

• transform_csv - Transform CSV data (add/remove/rename columns, filter rows)
• merge_csv - Merge two CSV files based on a common key

Data Updates

• update_cell - Update a specific cell value by row index and column name
• update_row - Update multiple fields in a specific row
• update_column - Update all values in a column (with value or formula)
• update_cells_conditional - Update cells matching a condition
• delete_rows - Delete rows by index or condition

Analysis & Statistics

• analyze_csv - Get statistics and analysis of CSV file
• aggregate_csv - Aggregate data with GROUP BY operations
• calculate_stats - Calculate advanced statistics (mean, median, stddev, percentiles, etc.)

Formulas & Calculations

• apply_formula - Apply mathematical formulas to CSV columns (e.g., column1 * column2)

Data Visualization

• generate_chart - Generate chart data for bar, line, pie, scatter, and histogram charts

🖥️ CLI Commands

The csv-mcp package provides several command-line tools for easy configuration:

Setup Commands

• csv-mcp init - Initialize CSV MCP in Claude Desktop

  npx csv-mcp init

Management Commands

• csv-mcp status - Show current configuration

  csv-mcp status

Information Commands

• csv-mcp --help/-h - Show help information
• csv-mcp --version/-v - Show version information
• csv-mcp --find-config - Show Claude Desktop config file location

💡 Usage Examples

Basic File Operations

"Read the /path/to/customers.csv file"
"Write this data to ~/output.csv: [data]"
"Show me information about ./sales.csv"

Querying Data

"Query /data/products.csv and select name, price where price > 100"
"Show me the first 10 rows of ~/users.csv sorted by age"
"Get unique values from the category column in ./products.csv"

Data Transformation

"Add a new column 'total' to ~/orders.csv by multiplying quantity and price"
"Remove the 'id' column from ./users.csv"
"Rename 'email' to 'email_address' in /data/contacts.csv"

Analysis

"Analyze the ~/sales.csv file and show me statistics"
"What's the average price in /data/products.csv?"
"Show me the top 10 most common values in the category column"
"Calculate mean, median, and standard deviation for the amount column in ~/sales.csv"
"Show me percentiles for the price column"

Formulas & Calculations

"Apply formula 'price * quantity' to /data/orders.csv and save result as 'total'"
"Calculate 'revenue - cost' for each row in ~/financials.csv"
"Add a column that multiplies column1 by 1.15 (15% increase)"
"Create a 'profit_margin' column using formula '(revenue - cost) / revenue * 100'"

Charts & Visualization

"Generate a bar chart from ~/sales.csv with month on X-axis and revenue on Y-axis"
"Create a pie chart showing sales distribution by category"
"Make a line chart of temperature data over time"
"Generate a scatter plot of height vs weight data"
"Create a histogram of age distribution in /data/customers.csv"

Cell/Row/Column Updates

"Update cell at row 5, column 'status' to 'completed' in tasks.csv"
"Update row 3 in customers.csv, set name to 'John' and email to '[email protected]'"
"Update the 'price' column in products.csv using formula 'price * 1.15'"
"Update all cells in 'status' column to 'active' where category is 'premium'"
"Delete rows 2, 5, and 7 from data.csv"
"Delete all rows where status is 'inactive' from users.csv"

Advanced Operations

"Merge /data/customers.csv and /data/orders.csv on customer_id"
"Group ~/sales.csv by category and sum the amounts"
"Search for 'john' in ./contacts.csv"

CLI Management Examples

# Initial setup (one-time)
npx csv-mcp init

# Check configuration
npx csv-mcp status

# Find config file location
npx csv-mcp --find-config

🔧 Configuration

No configuration needed! CSV MCP works with any file path you specify.

Setup (One-time)

Simply run:

npx csv-mcp init

This adds CSV MCP to your Claude Desktop configuration:

{
  "mcpServers": {
    "csv-mcp": {
      "command": "npx",
      "args": ["-y", "csv-mcp"]
    }
  }
}

Usage

Just specify file paths naturally in your requests:

• Absolute paths: /Users/john/data.csv, C:\Users\John\data.csv
• Home directory: ~/Documents/data.csv
• Relative paths: ./data.csv, ../data/file.csv

📚 Tool Details

read_csv

Read a CSV file and return its contents.

Parameters:

• filepath (required): Path to the CSV file
• limit (optional): Limit number of rows to read
• offset (optional): Number of rows to skip

Example:

{
  "filepath": "customers.csv",
  "limit": 100,
  "offset": 0
}

query_csv

Query a CSV file with SQL-like operations.

Parameters:

• filepath (required): Path to the CSV file
• select (optional): Array of column names to select
• where (optional): Filter conditions object
• orderBy (optional): Array of sort conditions
• limit (optional): Limit number of rows
• offset (optional): Skip number of rows
• distinct (optional): Return unique rows only

Example:

{
  "filepath": "products.csv",
  "select": ["name", "price", "category"],
  "where": {
    "column": "price",
    "operator": "gt",
    "value": 100
  },
  "orderBy": [
    { "column": "price", "direction": "desc" }
  ],
  "limit": 10
}

transform_csv

Transform CSV data by adding, removing, or renaming columns.

Parameters:

• filepath (required): Path to the CSV file
• outputPath (optional): Path for output file
• addColumn (optional): Add a new column
• removeColumn (optional): Remove a column
• renameColumn (optional): Rename a column

Example:

{
  "filepath": "orders.csv",
  "outputPath": "orders_with_total.csv",
  "addColumn": {
    "name": "total",
    "value": 0
  }
}

analyze_csv

Get statistics and analysis of a CSV file.

Parameters:

• filepath (required): Path to the CSV file
• column (optional): Specific column to analyze

Example:

{
  "filepath": "sales.csv",
  "column": "amount"
}

merge_csv

Merge two CSV files based on a common key.

Parameters:

• leftFile (required): Path to the left CSV file
• rightFile (required): Path to the right CSV file
• leftKey (required): Column name to join on in left file
• rightKey (required): Column name to join on in right file
• type (required): Type of join (inner, left, right, outer)
• outputPath (required): Path for output merged file

Example:

{
  "leftFile": "customers.csv",
  "rightFile": "orders.csv",
  "leftKey": "customer_id",
  "rightKey": "customer_id",
  "type": "inner",
  "outputPath": "customer_orders.csv"
}

aggregate_csv

Aggregate CSV data with GROUP BY operations.

Parameters:

• filepath (required): Path to the CSV file
• groupBy (required): Array of columns to group by
• aggregations (required): Array of aggregation functions
• outputPath (optional): Path for output file

Example:

{
  "filepath": "sales.csv",
  "groupBy": ["category", "region"],
  "aggregations": [
    { "column": "amount", "func": "sum", "alias": "total_sales" },
    { "column": "amount", "func": "avg", "alias": "avg_sale" },
    { "column": "order_id", "func": "count", "alias": "order_count" }
  ],
  "outputPath": "sales_summary.csv"
}

🧪 Testing

The CSV MCP server includes comprehensive testing:

# Run all tests
npm test

# Run only unit tests
npm run test:unit

# Run tests with coverage
npm run test:coverage

# Run tests in watch mode (development)
npm run test:watch

# Test CLI functionality
npm run test:cli

🏗️ Development

Local Development Setup

1. Clone the repository:

   git clone https://github.com/nitaiaharoni1/csv-mcp.git
   cd csv-mcp

2. Install dependencies:

   npm install

3. Build the project:

   npm run build

4. Test locally:

   npm run dev

Project Structure

csv-mcp/
├── src/
│   ├── csv/
│   │   ├── manager.ts      # CSV file operations
│   │   └── utils.ts        # CSV data manipulation utilities
│   ├── tools/
│   │   ├── csv-tools.ts    # MCP tool definitions
│   │   └── index.ts        # Tool registry
│   ├── types/
│   │   ├── csv.ts          # CSV type definitions
│   │   └── mcp.ts          # MCP type definitions
│   └── cli.ts              # CLI interface
├── server.ts               # MCP server entry point
└── package.json

📄 License

MIT License - See LICENSE file for details.

🙋‍♂️ Support

• GitHub Issues: Report bugs or request features
• Documentation: This README and inline code documentation
• Community: Contributions and discussions welcome!

🤝 Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

1. Fork the repository
2. Create your feature branch (git checkout -b feature/AmazingFeature)
3. Commit your changes (git commit -m 'Add some AmazingFeature')
4. Push to the branch (git push origin feature/AmazingFeature)
5. Open a Pull Request

Made with ❤️ for the AI and data community