mcp-csv-server by rickystanley76 - MCP 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

Install Python dependencies:

pip install -r requirements.txt

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

Add MCP Client Tool Node to your n8n workflow
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
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 for instructions on publishing this server for others to use with n8n.

See for deployment instructions and n8n configuration.

License

MIT License

Support

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