io.github.arpe-io/fastbcp-mcp
OfficialExports data from PostgreSQL databases to various file formats (CSV, TSV, JSON, Parquet, etc.) and storage targets (local, S3, Azure Blob, etc.) using FastBCP.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@io.github.arpe-io/fastbcp-mcppreview export from PostgreSQL table 'customers' to CSV"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
FastBCP MCP Server
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: Warp SQL Server MCP
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
Clone or download this repository:
cd /path/to/fastbcp-mcpInstall Python dependencies:
pip install -r requirements.txtConfigure environment:
cp .env.example .env # Edit .env with your FastBCP pathAdd 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" } } } }Restart Claude Code to load the MCP server.
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=INFOConnection Options
The server supports multiple ways to authenticate and connect:
Parameter | Description |
| Host:port or host\instance (optional with |
| Standard credentials |
| Windows trusted authentication |
| Full connection string (excludes server/user/password/dsn) |
| ODBC DSN name (excludes server/provider) |
| OleDB provider name |
| SQL Server application intent (ReadOnly/ReadWrite) |
Output Options
Option | CLI Flag | Description |
|
| Output format: csv, tsv, json, bson, parquet, xlsx, binary |
|
| Output file path |
|
| Output directory path |
|
| Storage: local, s3, s3compatible, azure_blob, azure_datalake, fabric_onelake |
|
| Field delimiter (CSV/TSV) |
|
| Quote character |
|
| Output encoding |
|
| Omit header row (CSV/TSV) |
|
| Decimal separator (. or ,) |
|
| Date format string |
|
| Boolean format: TrueFalse, OneZero, YesNo |
|
| Parquet compression: None, Snappy, Gzip, Lz4, Lzo, Zstd |
|
| Add timestamp to output filename |
|
| Merge parallel output files |
Export Options
Option | CLI Flag | Description |
|
| Parallelism method |
|
| Column for data distribution |
|
| Parallelism degree (default: 1) |
|
| Append or Truncate |
|
| Batch size for export operations |
|
| Column mapping: Position or Name |
|
| Run ID for logging |
|
| Custom SQL for DataDriven method |
|
| Custom settings JSON file |
|
| Override log level (Information/Debug) |
|
| Suppress banner output |
|
| License file path or URL |
|
| 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 approveExport 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:
Preview - Always use
preview_export_commandfirstExecute - Use
execute_exportwithconfirmation: 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,-gUse 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=htmlProject 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.mdLicense
This MCP server wrapper is provided as-is. FastBCP itself is a separate product from Arpe.io.
Related Links
Available Tools
6 toolsexecute_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.
| Name | Required | Description | Default |
|---|---|---|---|
| command | Yes | The exact command from preview_export_command (including actual passwords) | |
| confirmation | Yes | Must be true to execute. This confirms the user has reviewed the command. |
TDQS
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden. It discloses the safety mechanism requiring confirmation=true, which adds transparency. However, it does not describe potential side effects, return values, or error handling. For a execute tool, some behavioral details are missing.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is only two sentences, with the first sentence stating the core purpose and the second adding a critical usage note. It is front-loaded, efficient, and contains no unnecessary words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's simplicity (two parameters, no output schema, no annotations), the description is fairly complete. It covers what the tool does, how to invoke it (with confirmation=true), and the source of the command. It could mention what happens after execution (e.g., file output), but the description is adequate for an AI agent to use it correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Both parameters are documented in the schema (100% coverage). The description adds value by explaining that the 'command' parameter should be the exact output from preview_export_command and that 'confirmation' must be true. This provides additional context beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states it executes a previously previewed FastBCP export command. The verb 'execute' and resource 'FastBCP export command' are specific. It distinguishes from the sibling tool 'preview_export_command' by implying this is the actual execution step.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides explicit guidance: it must be used after preview, and the confirmation parameter must be set to true. It does not explicitly state when not to use it or list alternatives, but the safety mechanism note is helpful. The prerequisite of having run preview is implied.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
get_versionA
Get the detected FastBCP binary version, capabilities, and supported source types, output formats, and storage targets.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
TDQS
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description bears full responsibility for behavioral disclosure. It only states what is returned, but does not clarify side effects, authentication needs, caching, or whether the tool is safe to call repeatedly.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, well-structured sentence that efficiently conveys all necessary information without redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given no output schema, the description adequately lists the return categories. It could be more complete by specifying the format or structure, but for a simple version/capabilities tool, it provides sufficient context to understand what the tool returns.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool has zero parameters, so schema coverage is 100% by default. The description adds value by explaining the exact nature of the returned data (version, capabilities, supported types/formats/targets), which is beyond the empty schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb ('get') and clearly lists the resource ('FastBCP binary version, capabilities, and supported source types, output formats, and storage targets'). It distinguishes itself from sibling tools like 'list_supported_formats' by covering a broader set of information.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No explicit guidance on when to use this tool versus alternatives. The description does not mention prerequisites, typical use cases, or when not to use it.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
list_supported_formatsA
List all supported source databases, output formats, and storage targets.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
TDQS
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are present, and the description does not disclose any behavioral traits such as whether data is fetched dynamically, if it requires any prior setup, or if it has side effects. For a listing tool, this is minimal but acceptable given its simplicity.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence that concisely covers all relevant aspects without any superfluous information. It is front-loaded and efficient.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description adequately explains the tool's output scope given its simplicity. However, it lacks details about the output format (e.g., list structure) since no output schema is provided, leaving some ambiguity.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool has zero parameters, and schema coverage is 100%. The description does not need to add parameter semantics. A baseline of 4 is appropriate as there are no parameters to document.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description explicitly lists the three categories of information provided (source databases, output formats, storage targets), using a clear verb-resource structure. It distinguishes from siblings like execute_export or validate_connection by naming the specific listing function.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is given on when to use this tool versus alternatives. While the purpose implies it's for discovery before an export, there is no explicit mention of context or when not to use it.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
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.
| Name | Required | Description | Default |
|---|---|---|---|
| source | Yes | ||
| output | Yes | ||
| options | No | ||
| config_file | No | Path to a YAML configuration file (--config parameter, requires FastBCP 0.30+) | |
| os_type | No | Target operating system for command formatting | linux |
TDQS
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Without annotations, the description carries the full burden and discloses that the tool does not execute, shows the exact command with passwords masked. This is appropriate for a preview tool, though it could mention that it requires valid connection parameters to generate the command.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is three sentences long, with the most critical information (builds and previews without executing) first. Every sentence adds value without redundancy or waste.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the complexity of the input schema (nested objects, 5 parameters, no output schema, no annotations), the description is somewhat sparse. It adequately conveys the core purpose and usage direction but does not detail how the preview handles complex configurations like the config file or options, leaving some gaps for a complete understanding.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is only 40%, meaning many parameters lack adequate schema descriptions. The tool description does not add any parameter-specific semantics; it only mentions command preview and password masking. This is a missed opportunity to elaborate on key parameters like source, output, or options.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states it builds and previews a FastBCP export command without executing it. It distinguishes itself from the sibling 'execute_export' tool by explicitly stating it does not execute, making the purpose specific and unambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly advises to 'Use this FIRST before executing any export,' providing clear usage context for safe exploration. While it doesn't explicitly list when not to use, the sibling tool 'execute_export' serves as the alternative for actual execution, offering implicit guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
suggest_parallelism_methodA
Suggest the optimal parallelism method based on source database type and table characteristics. Provides recommendations for best performance.
| Name | Required | Description | Default |
|---|---|---|---|
| source_type | Yes | Source database type (e.g., 'pgsql', 'oraodp', 'mssql') | |
| has_numeric_key | Yes | Whether the table has a numeric key column | |
| has_identity_column | No | Whether the table has an identity/auto-increment column | |
| table_size_estimate | Yes | Estimated table size |
TDQS
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden of behavioral disclosure. It only mentions 'provides recommendations for best performance' but does not clarify if the tool has side effects (e.g., does it modify anything?), whether it requires prior setup, or how it handles errors. This is insufficient transparency for a tool that likely needs to be called before exporting.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely concise: two sentences totaling 18 words. Every word is relevant and contributes to the purpose. There is no unnecessary information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the low complexity of the tool (no nested objects, no output schema) and full schema coverage, the description is minimally adequate. However, it does not describe the output format (e.g., what does the suggestion look like? A string? An object?) which could be confusing for an agent. A score of 3 reflects this gap.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the baseline is 3. The description adds no additional meaning beyond the schema: it says 'based on source database type and table characteristics' which is a restatement of the parameters. No extra semantic value is provided.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's purpose: suggesting the optimal parallelism method based on source database type and table characteristics. The verb 'suggest' and resource 'parallelism method' are specific and differentiate it from sibling tools which focus on exporting, versioning, format listing, preview, and validation.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage for obtaining parallelism recommendations but does not provide explicit guidance on when to use this tool versus alternatives, nor does it state prerequisites or exclusions. The context from sibling tools provides some differentiation, but direct usage guidance is lacking.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
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).
| Name | Required | Description | Default |
|---|---|---|---|
| connection | Yes | ||
| side | Yes | Connection side |
TDQS
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, so description carries full burden. It clearly discloses that the tool only checks parameters and does not actually test connectivity. This is a key behavioral trait that prevents false expectations. Could mention if any side effects exist, but likely none.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences that are direct and front-loaded. Every sentence provides essential information: what it does and a critical limitation. No redundant or filler content.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a validation tool with no output schema, the description covers the purpose and behavioral limitation well. However, it does not describe the return format (e.g., success/failure indication). Since it is a straightforward validation, this is a minor gap.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 50%, but the tool description does not add much meaning beyond the schema. It mentions verifying 'required parameters' but does not detail which parameters are required or how they relate. The schema itself has descriptions for each parameter, so the description adds minimal value.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Clearly states the verb 'Validate' and resource 'source database connection parameters'. Distinguishes from a full connectivity test by explicitly stating what it does not do. Sibling tools like execute_export are unrelated, so purpose is unique and specific.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly says what the tool does (validate parameters) and what it does NOT do (test connectivity). Provides context that connectivity would require database access, but does not name a specific alternative tool. Still clear when to use this tool vs. other actions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
6 tool updates
v0.1.5- First observed
execute_export - First observed
get_version - First observed
list_supported_formats - First observed
preview_export_command - First observed
suggest_parallelism_method - First observed
validate_connection
TDQS
Scored across 6 tools
Each tool has a clearly distinct purpose: version info, format listing, connection validation (parameter check), command preview, execution, and parallelism suggestion. No overlap.
All tool names follow a consistent verb_noun pattern with underscores, e.g., execute_export, get_version, list_supported_formats. No mixing of conventions.
6 tools is well-scoped for a specialized export tool. Each tool covers a necessary step in the workflow without being excessive.
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
Related MCP Connectors
Push rows from a dataset, file or Google Sheet into a Postgres, Supabase, Neon or MySQL table.
Move a database between providers, or convert MySQL to PostgreSQL, with integrity verified.
Query, join, profile, clean and convert CSV/JSON/Parquet with server-side DuckDB over MCP.
Turn analyzed data into an Excel-like spreadsheet at a shareable URL: formulas, styles, filters.
Related MCP Servers
- AlicenseNot gradedqualityDmaintenanceA versatile tool that enables querying and exporting data from multiple relational databases (MySQL, PostgreSQL, Oracle, SQLite, etc.) in read-only mode for data safety.13Apache 2.0
- AlicenseBqualityAmaintenanceEnables 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.1696 npm6MIT
- AlicenseAqualityCmaintenanceEnables AI assistants to interact with Microsoft SQL Server databases through query execution, schema discovery, CRUD operations, stored procedures, and data export with built-in safety controls.18Apache 2.0
- AlicenseNot gradedqualityCmaintenanceExecutes SQL queries via ConnectorX and streams results to CSV or Parquet files, supporting multiple databases and optional token counting for CSV output.1MIT