fastbcp-mcp

FastBCP MCP 服务

一个 Model Context Protocol (MCP) 服务，用于提供 FastBCP 功能，将数据库中的数据导出到文件（CSV、TSV、JSON、BSON、Parquet、XLSX、Binary），并可选择云存储目标。

概述

FastBCP 是一款高性能命令行工具，用于将数据库中的数据导出到文件。此 MCP 服务封装了 FastBCP 功能，并提供：

• 安全优先：执行前预览命令，并要求用户确认
• 密码屏蔽：凭据和连接字符串绝不会显示在日志或输出中
• 智能验证：验证参数，并检查其与特定数据库的兼容性
• 智能建议：自动推荐并行处理方法
• 版本检测：自动检测二进制文件版本，并提供功能注册表
• 全面日志记录：记录完整的执行日志、时间戳和结果

MCP 工具

1. preview_export_command

构建并预览 FastBCP 导出命令，但不执行该命令。显示经过密码屏蔽的准确命令。请始终先使用此工具。

2. execute_export

执行此前预览过的命令。作为安全机制，必须设置 confirmation: true。

3. validate_connection

验证源数据库连接参数（仅检查参数，不测试实际连接）。

4. list_supported_formats

列出所有受支持的源数据库、输出格式和存储目标。

5. suggest_parallelism_method

根据源数据库类型和表特征，推荐最佳并行处理方法。

6. get_version

报告检测到的 FastBCP 二进制文件版本、支持的类型和功能标志。

安装

前提条件

• Python 3.10 或更高版本
• FastBCP 二进制文件 v0.29+（从 Arpe.io 获取）
• Claude Code 或其他 MCP 客户端

设置

1. 克隆或下载此仓库：

   cd /path/to/fastbcp-mcp
   

2. 安装 Python 依赖项：

   pip install -r requirements.txt
   

3. 配置环境：

   cp .env.example .env
   # Edit .env with your FastBCP path
   

4. 添加到 Claude Code 配置（~/.claude.json）：

   {
     "mcpServers": {
       "fastbcp": {
         "type": "stdio",
         "command": "python",
         "args": ["/absolute/path/to/fastbcp-mcp/src/server.py"],
         "env": {
           "FASTBCP_PATH": "/absolute/path/to/FastBCP"
         }
       }
     }
   }
   

5. 重启 Claude Code以加载 MCP 服务。

6. 验证安装：

   # In Claude Code, run:
   /mcp
   # You should see "fastbcp: connected"
   

配置

环境变量

编辑 .env 以进行配置：

# Path to FastBCP binary (required)
FASTBCP_PATH=./fastbcp/FastBCP

# Execution timeout in seconds (default: 1800 = 30 minutes)
FASTBCP_TIMEOUT=1800

# Log directory (default: ./logs)
FASTBCP_LOG_DIR=./logs

# Log level (default: INFO)
LOG_LEVEL=INFO

连接选项

此服务支持多种身份验证和连接方式：

参数	描述
server	主机:端口或主机\实例（与 connect_string 或 dsn 配合使用时可选）
user / password	标准凭据
trusted_auth	Windows 可信身份验证
connect_string	完整连接字符串（不包括 server/user/password/dsn）
dsn	ODBC DSN 名称（不包括 server/provider）
provider	OleDB 提供程序名称
application_intent	SQL Server 应用程序意向（ReadOnly/ReadWrite）

输出选项

选项	CLI 标志	描述
format	--format	输出格式：csv、tsv、json、bson、parquet、xlsx、binary
file_output	--fileoutput	输出文件路径
directory	--directory	输出目录路径
storage_target	--storagetarget	存储：local、s3、s3compatible、azure_blob、azure_datalake、fabric_onelake
delimiter	--delimiter	字段分隔符（CSV/TSV）
quotes	--quotes	引号字符
encoding	--encoding	输出编码
no_header	--noheader	省略标题行（CSV/TSV）
decimal_separator	--decimalseparator	小数分隔符（. 或 ,）
date_format	--dateformat	日期格式字符串
bool_format	--boolformat	布尔值格式：TrueFalse、OneZero、YesNo
parquet_compression	--parquetcompression	Parquet 压缩：None、Snappy、Gzip、Lz4、Lzo、Zstd
timestamped	--timestamped	在输出文件名中添加时间戳
merge	--merge	合并并行输出文件

导出选项

选项	CLI 标志	描述
method	--method	并行处理方法
distribute_key_column	--distributeKeyColumn	用于数据分发的列
degree	--degree	并行度（默认值：1）
load_mode	--loadmode	追加或截断
batch_size	--batchsize	导出操作的批量大小
map_method	--mapmethod	列映射：Position 或 Name
run_id	--runid	用于日志记录的运行 ID
data_driven_query	--datadrivenquery	DataDriven 方法的自定义 SQL
settings_file	--settingsfile	自定义设置 JSON 文件
log_level	--loglevel	覆盖日志级别（Information/Debug）
no_banner	--nobanner	禁止输出横幅
license_path	--license	许可证文件路径或 URL
cloud_profile	--cloudprofile	云存储配置文件名称

使用示例

PostgreSQL 导出为 CSV

User: "Export the 'orders' table from PostgreSQL (localhost:5432, database: sales_db,
       schema: public) to CSV file at /tmp/orders.csv. Use parallel export."

Claude Code will:
1. Call suggest_parallelism_method to recommend Ctid for PostgreSQL
2. Call preview_export_command with your parameters
3. Show the command with masked passwords
4. Explain what will happen
5. Ask for confirmation
6. Execute with execute_export when you approve

压缩后导出为 Parquet

User: "Export the 'transactions' table from SQL Server to Parquet format
       with Snappy compression, saved to /data/exports/."

Claude Code will use parquet format with parquet_compression set to Snappy.

导出到 S3

User: "Export the 'users' table from PostgreSQL to CSV on S3 bucket
       s3://my-bucket/exports/ using my AWS profile."

Claude Code will use storage_target=s3 with cloud_profile.

检查版本和功能

User: "What version of FastBCP is installed?"

Claude Code will call get_version and display the detected version,
supported source types, output formats, and available features.

两步安全流程

此服务实现了强制性的两步流程：

1. 预览 - 始终先使用 preview_export_command
2. 执行 - 使用 execute_export 并设置 confirmation: true

必须先预览并确认，才能执行。

安全

• 所有输出和日志中的密码及连接字符串都会被遮蔽
• 敏感标志会被遮蔽：--sourcepassword、--sourceconnectstring、-x、-g
• 对敏感配置使用环境变量
• 执行前仔细检查命令
• 使用所需的最低数据库权限

测试

运行测试套件：

# Run all tests
python -m pytest tests/ -v

# Run with coverage
python -m pytest tests/ --cov=src --cov-report=html

项目结构

fastbcp-mcp/
  src/
    __init__.py
    server.py          # MCP server (tool definitions, handlers)
    fastbcp.py         # Command builder, executor, suggestions
    validators.py      # Pydantic models, enums, validation
    version.py         # Version detection and capabilities registry
  tests/
    __init__.py
    test_command_builder.py
    test_validators.py
    test_version.py
  .env.example
  requirements.txt
  CHANGELOG.md
  README.md

许可证

此 MCP 服务封装按原样提供。FastBCP 本身是 Arpe.io 的独立产品。

相关链接

• FastBCP 文档
• 模型上下文协议