Skip to main content
Glama
io.github.arpe-io/fastbcp-mcp

io.github.arpe-io/fastbcp-mcp

Official
by aetperf

FastBCP MCP Server

PyPI License: MIT MCP Registry

A Model Context Protocol (MCP) server that exposes FastBCP functionality for exporting data from databases to files (CSV, TSV, JSON, BSON, Parquet, XLSX, Binary) with optional cloud storage targets.

Overview

FastBCP is a high-performance CLI tool for exporting data from databases to files. This MCP server wraps FastBCP functionality and provides:

  • Safety-first approach: Preview commands before execution with user confirmation required

  • Password masking: Credentials and connection strings are never displayed in logs or output

  • Intelligent validation: Parameter validation with database-specific compatibility checks

  • Smart suggestions: Automatic parallelism method recommendations

  • Version detection: Automatic binary version detection with capability registry

  • Comprehensive logging: Full execution logs with timestamps and results

Related MCP server: run-sql-connectorx

MCP Tools

1. preview_export_command

Build and preview a FastBCP export command WITHOUT executing it. Shows the exact command with passwords masked. Always use this first.

2. execute_export

Execute a previously previewed command. Requires confirmation: true as a safety mechanism.

3. validate_connection

Validate source database connection parameters (parameter check only, does not test actual connectivity).

4. list_supported_formats

List all supported source databases, output formats, and storage targets.

5. suggest_parallelism_method

Recommend the optimal parallelism method based on source database type and table characteristics.

6. get_version

Report the detected FastBCP binary version, supported types, and feature flags.

Installation

Prerequisites

  • Python 3.10 or higher

  • FastBCP binary v0.29+ (obtain from Arpe.io)

  • Claude Code or another MCP client

Setup

  1. Clone or download this repository:

    cd /path/to/fastbcp-mcp
  2. Install Python dependencies:

    pip install -r requirements.txt
  3. Configure environment:

    cp .env.example .env
    # Edit .env with your FastBCP path
  4. Add to Claude Code configuration (~/.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. Restart Claude Code to load the MCP server.

  6. Verify installation:

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

Configuration

Environment Variables

Edit .env to configure:

# 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

Connection Options

The server supports multiple ways to authenticate and connect:

Parameter

Description

server

Host:port or host\instance (optional with connect_string or dsn)

user / password

Standard credentials

trusted_auth

Windows trusted authentication

connect_string

Full connection string (excludes server/user/password/dsn)

dsn

ODBC DSN name (excludes server/provider)

provider

OleDB provider name

application_intent

SQL Server application intent (ReadOnly/ReadWrite)

Output Options

Option

CLI Flag

Description

format

--format

Output format: csv, tsv, json, bson, parquet, xlsx, binary

file_output

--fileoutput

Output file path

directory

--directory

Output directory path

storage_target

--storagetarget

Storage: local, s3, s3compatible, azure_blob, azure_datalake, fabric_onelake

delimiter

--delimiter

Field delimiter (CSV/TSV)

quotes

--quotes

Quote character

encoding

--encoding

Output encoding

no_header

--noheader

Omit header row (CSV/TSV)

decimal_separator

--decimalseparator

Decimal separator (. or ,)

date_format

--dateformat

Date format string

bool_format

--boolformat

Boolean format: TrueFalse, OneZero, YesNo

parquet_compression

--parquetcompression

Parquet compression: None, Snappy, Gzip, Lz4, Lzo, Zstd

timestamped

--timestamped

Add timestamp to output filename

merge

--merge

Merge parallel output files

Export Options

Option

CLI Flag

Description

method

--method

Parallelism method

distribute_key_column

--distributeKeyColumn

Column for data distribution

degree

--degree

Parallelism degree (default: 1)

load_mode

--loadmode

Append or Truncate

batch_size

--batchsize

Batch size for export operations

map_method

--mapmethod

Column mapping: Position or Name

run_id

--runid

Run ID for logging

data_driven_query

--datadrivenquery

Custom SQL for DataDriven method

settings_file

--settingsfile

Custom settings JSON file

log_level

--loglevel

Override log level (Information/Debug)

no_banner

--nobanner

Suppress banner output

license_path

--license

License file path or URL

cloud_profile

--cloudprofile

Cloud storage profile name

Usage Examples

PostgreSQL to CSV Export

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

Export to Parquet with Compression

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.

Export to 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.

Check Version and Capabilities

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.

Two-Step Safety Process

This server implements a mandatory two-step process:

  1. Preview - Always use preview_export_command first

  2. Execute - Use execute_export with confirmation: true

You cannot execute without previewing first and confirming.

Security

  • Passwords and connection strings are masked in all output and logs

  • Sensitive flags masked: --sourcepassword, --sourceconnectstring, -x, -g

  • Use environment variables for sensitive configuration

  • Review commands carefully before executing

  • Use minimum required database permissions

Testing

Run the test suite:

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

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

Project Structure

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

License

This MCP server wrapper is provided as-is. FastBCP itself is a separate product from Arpe.io.

Available Tools

6 tools
execute_exportA

Execute a FastBCP export command that was previously previewed. IMPORTANT: You must set confirmation=true to execute. This is a safety mechanism to prevent accidental execution.

Inputs: command (required), confirmation (required).

get_versionA

Get the detected FastBCP binary version, capabilities, and supported source types, output formats, and storage targets.

Inputs: no named parameters.

list_supported_formatsA

List all supported source databases, output formats, and storage targets.

Inputs: no named parameters.

preview_export_commandA

Build and preview a FastBCP export command WITHOUT executing it. This shows the exact command that will be run, with passwords masked. Use this FIRST before executing any export.

Inputs: source (required), output (required), options, config_file, +1 more.

suggest_parallelism_methodA

Suggest the optimal parallelism method based on source database type and table characteristics. Provides recommendations for best performance.

Inputs: source_type (required), has_numeric_key (required), table_size_estimate (required), has_identity_column.

validate_connectionA

Validate source database connection parameters. This checks that all required parameters are provided but does NOT actually test connectivity (would require database access).

Inputs: connection (required), side (required).

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    A4/5.0

    Scored across 6 tools

    Disambiguation5/5

    Each tool has a clearly distinct purpose: version info, format listing, connection validation (parameter check), command preview, execution, and parallelism suggestion. No overlap.

    Naming Consistency5/5

    All tool names follow a consistent verb_noun pattern with underscores, e.g., execute_export, get_version, list_supported_formats. No mixing of conventions.

    Tool Count5/5

    6 tools is well-scoped for a specialized export tool. Each tool covers a necessary step in the workflow without being excessive.

    Completeness4/5

    Covers the main export workflow (preview, execute) along with auxiliary functions (version, formats, parallelism). Minor gap: no actual connectivity test, but parameter validation is present.

    Maintenance

    ActivityInactive
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      B
      quality
      A
      maintenance
      Enables secure database operations on SQL Server instances through a three-tier safety system, supporting schema exploration, query execution, performance analysis, and data export with configurable security levels from read-only to full development access.
      2
      16
      35 npm
      6
      MIT
    • A
      license
      Not graded
      quality
      D
      maintenance
      Executes SQL queries via ConnectorX and streams results to CSV or Parquet files, supporting multiple databases and optional token counting for CSV output.
      1
      MIT
    • F
      license
      A
      quality
      B
      maintenance
      Enables agents to interact with MySQL databases securely, supporting multi-database read-only queries, protected DML writes, and streaming exports to Sandbox Datasets.
      5
      -
    • A
      license
      Not graded
      quality
      B
      maintenance
      Enables AI agents to query Excel, CSV, Parquet, and NDJSON files as SQL tables, joining data across formats and sheets and exporting results to CSV or Excel.
      1
      Apache 2.0