README.md•4.31 kB
# 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
```bash
uv add csv-mcp-server
```
## Usage
### Running the Server
```bash
# 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
```python
# 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