CSV MCP Server

A Model Context Protocol (MCP) server for comprehensive CSV file management using stdio transport exclusively. This server provides tools for creating, editing, analyzing, and managing CSV files using the MCP protocol over standard input/output.

Features

File Management: Create, read, update, and delete CSV files
Absolute Path Support: Work with CSV files anywhere in the filesystem using absolute paths
Data Analysis: Basic statistical analysis and data exploration
Data Transformation: Filter, sort, group, and transform data
Data Validation: Check data integrity and format validation
Import/Export: Support for various CSV formats and encodings
Stdio Transport: Uses JSON-RPC 2.0 over standard input/output for communication

Installation

uv add csv-mcp-server

Usage

Running the Server

# Using stdio transport (default and only option)
uv run csv-mcp-server

# With custom log level
uv run csv-mcp-server --log-level DEBUG

# Development mode
uv run mcp dev csv_mcp_server/server.py

Available Tools

create_csv: Create a new CSV file with headers and initial data
create_csv_at_path: Create a CSV file at a specific absolute or relative path
read_csv: Read and display CSV file contents
update_csv: Update specific cells or rows in a CSV file
delete_csv: Delete a CSV file
add_row: Add new rows to an existing CSV file
remove_row: Remove specific rows from a CSV file
get_info: Get basic information about a CSV file
get_statistics: Get statistical summary of numeric columns
filter_data: Filter CSV data based on conditions
sort_data: Sort CSV data by specified columns
group_data: Group and aggregate CSV data
validate_data: Validate CSV data integrity and format
get_path_info: Get detailed information about a file path (supports absolute paths)

Available Resources

csv://{filename}: Access CSV file contents as a resource
csv-info://{filename}: Get metadata about a CSV file

Available Prompts

analyze_csv: Generate analysis prompts for CSV data
transform_csv: Generate transformation suggestions

Configuration

The server can be configured with environment variables:

CSV_STORAGE_PATH: Base path for CSV file storage (default: current directory)
CSV_MAX_FILE_SIZE: Maximum file size in MB (default: 50)
CSV_BACKUP_ENABLED: Enable automatic backups (default: true)
CSV_SUPPORT_ABSOLUTE_PATHS: Enable absolute path support (default: true)

Absolute Path Support

The CSV MCP server now supports working with CSV files anywhere in the filesystem using absolute paths. This feature allows you to:

Create CSV files in any accessible directory
Read and modify existing CSV files from anywhere on the system
Work with files outside the default storage directory
Maintain backward compatibility with relative paths

Security Features

Path Validation: Automatically validates absolute paths for safety
System Directory Protection: Prevents access to critical system directories
Permission Checking: Verifies directory and file access permissions
Symlink Resolution: Safely resolves symbolic links to prevent path traversal attacks

Usage Examples

# Create a CSV file at an absolute path
create_csv_at_path(
    filepath="/path/to/your/data/sales.csv",
    headers=["Date", "Product", "Sales"],
    data=[["2024-01-01", "Laptop", 1200]]
)

# Get information about any file path
get_path_info(filepath="/path/to/your/file.csv")

# All existing tools work with absolute paths
read_csv("/path/to/your/data/analysis.csv")
update_csv("/path/to/your/data/analysis.csv", row_index=0, column="Sales", value=1500)

Transport

This server exclusively uses stdio transport with JSON-RPC 2.0 protocol, making it ideal for:

Integration with MCP clients that support stdio transport
Command-line tools and scripts
Development and testing environments
Containerized deployments

Examples

See the examples/ directory for usage examples with various MCP clients:

demo_client.py: Basic MCP client demonstration
sales_analysis.py: Sales data analysis example
absolute_path_demo.py: Demonstration of absolute path functionality