MCP Csv Postgres

🚀 CSV到PostgreSQL MCP服务器

这是一个MCP（模型上下文协议）服务器，可将CSV文件加载到PostgreSQL数据库中，并具备验证和进度跟踪功能。

🚀 快速开始

本项目是一个MCP服务器，能将CSV文件加载到PostgreSQL数据库，同时提供验证和进度跟踪功能。以下是使用前的安装和使用步骤。

✨ 主要特性

• CSV验证：验证CSV文件结构，并提供详细的错误信息。
• 高效加载：使用PostgreSQL的COPY命令进行快速批量加载。
• 进度跟踪：在长时间导入操作中显示进度条。
• 灵活配置：可选择数据库名称（默认为csvimports）。
• 错误报告：提供验证错误的精确行号和列信息。

📦 安装指南

从PyPI安装

pip install mcp-csv-postgres

或者使用uv安装：

uv pip install mcp-csv-postgres

从源代码安装

克隆仓库并使用uv安装：

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

💻 使用示例

作为MCP服务器使用

选项1：从PyPI安装后

将以下内容添加到Claude桌面配置文件（macOS上为~/Library/Application Support/Claude/claude_desktop_config.json）：

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

选项2：用于本地开发

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

或者直接从命令行运行：

mcp-csv-postgres

工具：load_csv_to_postgres

将CSV文件加载到PostgreSQL数据库。 参数：

• file_path（必需）：CSV文件的路径。
• dbname（可选）：数据库名称（默认为csvimports）。
• host（可选）：PostgreSQL主机（默认为localhost）。
• port（可选）：PostgreSQL端口（默认为5432）。
• user（可选）：PostgreSQL用户（默认为postgres）。
• password（可选）：PostgreSQL密码。
• table_name（可选）：表名（如果未提供，则从文件名派生）。 返回值：
• 包含数据库名称、表名和加载行数的成功消息。
• 包含详细验证或数据库错误的错误消息。

📚 详细文档

测试服务器

快速测试

运行测试脚本以查看服务器的运行情况：

uv run python test_server.py

此命令将执行以下操作：

1. 创建示例CSV文件。
2. 测试将其加载到PostgreSQL。
3. 测试验证错误报告。
4. 显示详细输出。

使用示例数据进行手动测试

sample_data.csv中提供了一个示例CSV文件。要手动测试：

# 在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)

使用MCP Inspector进行测试

要使用MCP Inspector工具进行测试：

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

VS Code启动配置

.vscode/launch.json包含以下配置：

• 运行MCP服务器：以调试模式启动服务器。
• 使用示例CSV测试MCP服务器：运行测试脚本。
• 运行所有测试：执行完整的测试套件。
• 运行特定测试：调试单个测试文件。

开发

运行测试

uv run pytest

代码覆盖率

uv run pytest --cov-report=html

覆盖率报告将在htmlcov/index.html中提供。当前覆盖率：>90%。

预提交钩子

预提交钩子配置为在每次提交前运行测试：

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

架构

模块

• validator.py：具有详细错误报告的CSV验证。
  • 文件存在性和可读性检查。
  • CSV结构验证。
  • 行一致性验证。
  • 自动方言检测。
• database.py：PostgreSQL数据库操作。
  • 连接管理。
  • 数据库创建。
  • 根据CSV表头创建表。
  • 行计数。
• loader.py：使用COPY命令加载CSV。
  • 使用tqdm进行进度跟踪。
  • 高效批量加载。
  • 错误处理和回滚。
• server.py：MCP服务器实现。
  • 标准输入输出传输。
  • 工具注册。
  • 错误处理。

错误处理

服务器提供详细的错误消息：

• 验证错误：CSV问题的精确行号和描述。
• 数据库错误：连接、权限和SQL错误。
• 文件错误：权限、编码和文件未找到错误。

示例

加载CSV文件

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

使用自定义数据库

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

📄 许可证

本项目采用MIT许可证。