MCP Csv Postgres

🚀 CSV to PostgreSQL MCP Server

An MCP (Model Context Protocol) server that loads CSV files into PostgreSQL databases with validation and progress tracking.

🚀 Quick Start

This MCP server enables you to load CSV files into PostgreSQL databases while validating the data and tracking the progress.

✨ Features

• CSV Validation: Validates the structure of CSV files and provides detailed error messages.
• Efficient Loading: Utilizes the PostgreSQL COPY command for fast bulk loading.
• Progress Tracking: Displays a progress bar for long - running imports.
• Flexible Configuration: Allows an optional database name (defaults to csvimports).
• Error Reporting: Provides exact line numbers and column information for validation errors.

📦 Installation

From PyPI

pip install mcp-csv-postgres

Or using uv:

uv pip install mcp-csv-postgres

From Source

Clone the repository and install with uv:

git clone https://github.com/raviramadoss/mcp-csv-postgres.git
cd mcp-csv-postgres
uv sync --all-extras

💻 Usage Examples

As MCP Server

Option 1: After installing from PyPI

Add to your Claude Desktop configuration file (~/Library/Application Support/Claude/claude_desktop_config.json on macOS):

{
  "mcpServers": {
    "mcp-csv-postgres": {
      "command": "uv",
      "args": [
        "tool",
        "run",
        "--from",
        "mcp-csv-postgres",
        "mcp-csv-postgres"
      ]
    }
  }
}

Option 2: For local development

{
  "mcpServers": {
    "mcp-csv-postgres": {
      "command": "uv",
      "args": [
        "tool",
        "run",
        "--from",
        "/path/to/mcp-csv-postgres",
        "--python",
        "3.10",
        "mcp-csv-postgres"
      ]
    }
  }
}

Or run directly from the command line:

mcp-csv-postgres

Tool: load_csv_to_postgres

Loads a CSV file into a PostgreSQL database.

Parameters:

• file_path (required): Path to the CSV file.
• dbname (optional): Database name (default: csvimports).
• host (optional): PostgreSQL host (default: localhost).
• port (optional): PostgreSQL port (default: 5432).
• user (optional): PostgreSQL user (default: postgres).
• password (optional): PostgreSQL password.
• table_name (optional): Table name (derived from the filename if not provided).

Returns:

• A success message with the database name, table name, and the number of rows loaded.
• An error message with detailed validation or database errors.

📚 Documentation

Testing the Server

Quick Test

Run the test script to see the server in action:

uv run python test_server.py

This will:

1. Create sample CSV files.
2. Test loading them into PostgreSQL.
3. Test validation error reporting.
4. Show detailed output.

Manual Testing with Sample Data

A sample CSV file is provided in sample_data.csv. To test manually:

# In Python/IPython
import asyncio
from mcp_csv_postgres.server import call_tool

result = asyncio.run(call_tool(
    "load_csv_to_postgres",
    {"file_path": "sample_data.csv"}
))
print(result[0].text)

Using with MCP Inspector

To test with the MCP Inspector tool:

npx @modelcontextprotocol/inspector uv run mcp-csv-postgres

VS Code Launch Configurations

The .vscode/launch.json includes:

• Run MCP Server: Start the server in debug mode.
• Test MCP Server with Sample CSV: Run the test script.
• Run All Tests: Execute the full test suite.
• Run Specific Test: Debug a single test file.

Development

Running Tests

uv run pytest

Code Coverage

uv run pytest --cov-report=html

The coverage report will be available in htmlcov/index.html. Current coverage: >90%

Pre - commit Hooks

Pre - commit hooks are configured to run tests before each commit:

uv run pre-commit install
uv run pre-commit run --all-files

🔧 Technical Details

Architecture

Modules

• validator.py: Performs CSV validation with detailed error reporting.

  • Checks file existence and readability.
  • Validates the CSV structure.
  • Validates row consistency.
  • Automatically detects the dialect.

• database.py: Handles PostgreSQL database operations.

  • Manages connections.
  • Creates databases.
  • Creates tables from CSV headers.
  • Counts rows.

• loader.py: Loads CSV files using the COPY command.

  • Tracks progress with tqdm.
  • Performs efficient bulk loading.
  • Handles errors and rollbacks.

• server.py: Implements the MCP server.

  • Uses stdio transport.
  • Registers tools.
  • Handles errors.

Error Handling

The server provides detailed error messages:

• Validation Errors: Include exact line numbers and descriptions of CSV issues.
• Database Errors: Such as connection, permission, and SQL errors.
• File Errors: Like permission, encoding, and file not found errors.

💻 Usage Examples

Basic Usage

{
  "tool": "load_csv_to_postgres",
  "arguments": {
    "file_path": "/path/to/data.csv"
  }
}

Advanced Usage

{
  "tool": "load_csv_to_postgres",
  "arguments": {
    "file_path": "/path/to/data.csv",
    "dbname": "mydb",
    "table_name": "my_table"
  }
}

📄 License

MIT