MCP Csv Server

MCP CSV Server

A Model Context Protocol (MCP) server that provides comprehensive CSV data management capabilities including CRUD operations and data analysis. Designed to integrate seamlessly with n8n-mcp client.

Features

• Full CRUD Operations: Create, Read, Update, and Delete records in CSV files
• Data Analysis: Statistical operations (mean, sum, count, min, max, std, median)
• Search Functionality: Text search across CSV columns
• Schema Detection: Automatic column type detection and schema information
• n8n Integration: HTTP transport compatible with n8n-mcp client
• Generic CSV Support: Works with any CSV file structure

Installation

1. Install Python dependencies:

pip install -r requirements.txt

1. Configure environment variables (optional):

cp .env.example .env
# Edit .env file with your settings

Usage

Starting the Server

HTTP Server (for n8n-mcp client):

python -m mcp_csv_server.server

Stdio Server (for direct MCP clients):

python -m mcp_csv_server.server stdio

The server will start on http://0.0.0.0:8000 by default.

Available Endpoints

• GET / - Server information
• GET /health - Health check
• GET /tools - List all available tools
• POST /tools/{tool_name} - Execute a tool (simple REST API)
• POST /mcp - Unified MCP endpoint for HTTP transport (n8n-mcp client)

MCP Tools

1. csv_list_files

List all available CSV files in the data directory.

Example:

{
  "filename": null
}

2. csv_get_schema

Get schema information for a CSV file.

Parameters:

• filename (string, required): Name of the CSV file

Example:

{
  "filename": "data.csv"
}

3. csv_read

Read data from a CSV file with optional filtering and pagination.

Parameters:

• filename (string, required): Name of the CSV file
• filters (object, optional): Filter conditions as key-value pairs
• limit (integer, optional): Maximum number of rows to return
• offset (integer, optional): Number of rows to skip (default: 0)

Example:

{
  "filename": "data.csv",
  "filters": {"status": "active"},
  "limit": 10,
  "offset": 0
}

4. csv_create

Create a new record in a CSV file.

Parameters:

• filename (string, required): Name of the CSV file
• record (object, required): Record data as key-value pairs

Example:

{
  "filename": "data.csv",
  "record": {
    "name": "John Doe",
    "email": "john@example.com",
    "age": 30
  }
}

5. csv_update

Update an existing record in a CSV file.

Parameters:

• filename (string, required): Name of the CSV file
• index (integer, required): Row index (0-based)
• updates (object, required): Fields to update as key-value pairs

Example:

{
  "filename": "data.csv",
  "index": 0,
  "updates": {
    "email": "newemail@example.com"
  }
}

6. csv_delete

Delete a record from a CSV file.

Parameters:

• filename (string, required): Name of the CSV file
• index (integer, required): Row index (0-based)

Example:

{
  "filename": "data.csv",
  "index": 0
}

7. csv_search

Search for text within CSV data.

Parameters:

• filename (string, required): Name of the CSV file
• query (string, required): Text to search for
• columns (array, optional): List of column names to search (empty = all columns)

Example:

{
  "filename": "data.csv",
  "query": "John",
  "columns": ["name", "email"]
}

8. csv_analyze

Perform statistical analysis on CSV data.

Parameters:

• filename (string, required): Name of the CSV file
• operations (array, optional): List of operations to perform (mean, sum, count, min, max, std, median). Empty = all operations

Example:

{
  "filename": "data.csv",
  "operations": ["mean", "sum", "count"]
}

n8n-mcp Client Configuration

Setup in n8n

1. Add MCP Client Tool Node to your n8n workflow
2. Configure the connection:

- Server Transport: Select "HTTP" or "HTTP Streamable" - Endpoint URL: http://your-server:8000/mcp - Authentication: None (or configure as needed) - Tools to Include: Select the CSV tools you want to use

1. Use in AI Agent workflows:

- Connect the MCP Client Tool node to an AI Agent node - The AI Agent can now use the CSV tools to interact with your data

Example n8n Workflow

Webhook Trigger → MCP Client Tool → AI Agent → Response

The AI Agent can now execute queries like:

• "List all CSV files"
• "Read the first 10 rows from data.csv"
• "Find all records where status is 'active'"
• "Calculate the average age from users.csv"

CSV File Format

• CSV files should be placed in the data/ directory (configurable via CSV_DATA_DIR env var)
• Standard CSV format with comma delimiter
• First row should contain column headers
• Supports UTF-8 encoding
• Automatic type detection for numeric columns

Configuration

Environment Variables

• CSV_DATA_DIR - Directory path containing CSV files (default: data)
• SERVER_HOST - Server host (default: 0.0.0.0)
• SERVER_PORT - Server port (default: 8000)
• MCP_ENDPOINT - MCP endpoint path (default: /mcp)
• CORS_ORIGINS - CORS allowed origins, comma-separated (default: *)
• MAX_FILE_SIZE_MB - Maximum file size in MB (default: 100)

Security Considerations

• File paths are validated to prevent directory traversal attacks
• Only files within the configured data directory are accessible
• Consider implementing authentication for production deployments
• Restrict CORS origins in production environments

Development

Project Structure

mcp_csv_server/
├── __init__.py
├── server.py              # Main MCP server with HTTP transport
├── csv_handler.py         # CSV operations (CRUD + analysis)
└── tools.py                # MCP tool definitions

Testing

Test the server endpoints using curl or Postman:

# Health check
curl http://localhost:8000/health

# List tools
curl http://localhost:8000/tools

# Execute a tool
curl -X POST http://localhost:8000/tools/csv_list_files \
  -H "Content-Type: application/json" \
  -d "{}"

Publishing for Others

See PUBLISHING.md for instructions on publishing this server for others to use with n8n.

See DEPLOYMENT.md for deployment instructions and n8n configuration.

License

MIT License

Support

• Issues: https://github.com/rickystanley76/mcp-csv-server/issues
• Documentation: See DEPLOYMENT.md for n8n setup
• For MCP protocol questions, refer to the MCP documentation