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許可證。