Bauplan tools, MCP Server & Agent Skills

Build AI-powered data engineering workflows with the Bauplan MCP Server and Agent Skills.

[!NOTE]

This project is released in Beta under MIT license. APIs and features may change without notice as we continue development.

Overview

This repository provides three complementary tools for AI-assisted data engineering with Bauplan:

1. Repository-based usage (CLAUDE.md + reference documentation) - Add Bauplan workflow guidance and CLI reference directly to your repository's .claude/ directory so AI coding assistants automatically understand Bauplan commands, safety rules, and your team's conventions without requiring tool integrations.

2. Agent Skills - Reusable skill definitions for Claude Code that provide guided workflows for common code generation tasks like creating pipelines (/data-pipeline) and data ingestion (/safe-ingestion).

3. MCP Server - A Model Context Protocol server that gives AI assistants (Claude Code, Claude Desktop, Cursor) access to Bauplan lakehouse operations: querying tables, schema inspection, branch management, and running pipelines. A video walkthrough demonstrates setup and usage.

The intended usage for this repo is to help with *local development* by providing AI assistants access to your Bauplan lakehouse: a blog post with some context and background is available here.

Repository-based usage (CLAUDE.md + references)

Bauplan can be used with AI coding assistants without running the MCP server, by providing the assistant with explicit, repository-local context. In this mode, the assistant operates by reading documentation, writing code, and invoking Bauplan through the CLI or Python SDK.

This is the recommended default for IDE-based assistants such as Claude Code or Cursor.

How it works

The integration is entirely file-based. You give the assistant:

1. **An agent playbook (CLAUDE.md)** that explains how to work with Bauplan

2. Reference documentation it can consult for correct CLI and SDK usage

3. Optional Skills that template multi-step workflows

The assistant then:

• Reads instructions from CLAUDE.md
• Writes Python or SQL in your repository
• Runs explicit Bauplan CLI commands or SDK calls
• Follows the same branch, run, validate, publish workflow a human would

No background service or MCP transport is required.

Repository structure

A typical setup looks like this:

your-repository/
├── .claude/
│   ├── CLAUDE.md
│   ├── bauplan-reference/
│   │   └── bauplan_cli.md
│   └── skills/
│       ├── data-pipeline/
│       │   └── SKILL.md
│       ├── safe-ingestion/
│       │   └── SKILL.md
│       ├── data-quality-checks/
│       │   └── SKILL.md
│       ├── explore-data/
│       │   └── SKILL.md
│       ├── debug-and-fix-pipeline/
│       │   └── SKILL.md
│       └── data-assessment/
│           └── SKILL.md
├── your-bauplan-project/
│   ├── models.py
│   └── bauplan_project.yml
└── README.md

Bauplan (agent playbook) with CLAUDE.md

CLAUDE.md is the primary control surface for the assistant.

It defines:

• When to use Skills vs direct CLI / SDK calls
• How to create and manage data branches
• How to run pipelines safely (never write to main)
• How to validate results and publish changes
• How to retrieve detailed instructions

For Claude Code, CLAUDE.md is automatically loaded and used as context on every interaction. For other tools, its contents can be used as a system prompt or initial context.

Reference documentation

The ./claude/bauplan-reference/ directory contains authoritative documentation for the Bauplan CLI and SDK. Assistants use this to verify syntax, flags, and expected behavior before executing commands.

This avoids hallucinated commands and keeps generated code aligned with the actual API surface.

Skills

[!WARNING]

Skills are very experimental and subject to change at any time.

The skills/ folder contains reusable skill definitions for Claude Code that provide guided workflows for common Bauplan tasks. These skills can be incorporated into your Claude Code projects to enable AI-assisted data engineering.

Available Skills

Using Skills

To incorporate these skills into your Claude Code projects, see the official documentation on distributing and installing skills. Each skill folder contains the skill definitinon along with examples and usage patterns.

Developer Notes

If you are actively developing within this repo, an experimental integration test suite is available in tests/. These integration tests treat Claude as a black box process: a prompt is fed to Claude in non-interactive mode, and the output is analyzed to verify appropriate skill and tool usage, as well as the presence of expected side effects in the lakehouse (i.e., did the system accomplish the goal?).

While not perfect, this setup allows us to rapidly iterate on Bauplan-related affordances with some level of confidence and some degree of repeatability (i.e., even as models evolve and prompts change, we can verify that certain core LLM decisions remain intact, for example, using safe-ingestion as a skill when prompts mention safe data ingestion). To run the tests from the root, you can use pytest and specify a real S3 file for testing:

BAUPLAN_TEST_S3_PATH="s3://public-read-bucket/my-file.parquet" uv run pytest -v

As best practices emerge, Bauplan skills multiply and AI-assisted workflows rise, this suite will evolve to provide more comprehensive coverage and guidance.

MCP Quick Start

You can get started in one minute with your existing AI assistant: a video setup with Claude Desktop and Claude Code is also available here for reference.

You need:

• a Bauplan API key properly configured in your local config file (default profile) - the server will pick it up automatically (see below for alternative authentication methods);
• uv (or a standard pip managed virtual environment, see below);
• an AI platform able to leverage the MCP, as for example Claude Code, Cursor, Claude Desktop.

[!WARNING]

do not use an Admin Bauplan API key: while the server will refuse to write on main, it is good practice to use a non-admin key for AI-assisted development (see our roadmap below for more details on upcoming security features).

Start the server with:

uv sync
uv run python main.py --transport streamable-http

The MCP server is now available at http://localhost:8000/mcp. You can configure the server in Claude Code for example with:

claude mcp add -t http mcp-bauplan http://localhost:8000/mcp

Similar commands can be run on Claude Desktop or Cursor to enable the AI to access the server.

Et voilà! You can now start asking your AI questions about your data lakehouse (and much more!).

Documentation

CLAUDE.md for Guided Usage

A CLAUDE.md file is provided at the repository root that instructs the model on how to best use the Bauplan MCP server and the Bauplan skills provided in the skills/ folder.

For Claude Code users: Claude Code automatically picks up CLAUDE.md files and uses them as context for every interaction. This ensures the model knows:

• Decision tree for when to use skills (/data-pipeline, /safe-ingestion, /data-quality-checks, /explore-data, /debug-and-fix-pipeline, /data-assessment) vs MCP tools vs CLI/SDK
• How to retrieve detailed instructions via get_instructions
• How to verify SDK/CLI syntax
• Canonical workflows for common tasks

For other MCP clients, include the contents as a system prompt or initial context.

CLI Reference

Comprehensive reference documentation for the Bauplan CLI is available in bauplan_reference/cli.md. This includes:

• Full command syntax and options
• Common workflows and examples
• Detailed parameter descriptions

Advanced Configurations

Bauplan Credentials

The Beta release covers the local development use case. Authentication to your Bauplan lakehouse happens as follows:

• if you do not specify a Bauplan profile as a flag, the default one on the machine running the server will be used at every interaction with the lakehouse.
• if you specify a profile as a flag, this profile will be used instead when instantiating a Bauplan client.
• if you specify a header in your assistant - key=Bauplan, value=your_api_key (e.g. in Claude code claude mcp add -H "Bauplan: " ...) -, your_api_key will be used instead when instantiating a Bauplan client. This is convenient for quick tests, and opens up the possibility of hosting the catalog on a shared infrastructure, delegating to clients the Bauplan API key management.

Server CLI Options

The server supports the following CLI options, mostly useful for specifying alternative transport options:

Note: The --host and --port options are ignored when using stdio transport since it communicates through stdin/stdout.

Claude Desktop

To add the Bauplan MCP server to Claude Desktop, follow the guide to get to your claude_desktop_config.json file.

Automatic Configuration Generation

Use the provided script to generate the configuration with the correct paths:

uv run scripts/generate-config.py

This will output a JSON configuration with all paths properly set to your installation directory. Copy the output and add it to your claude_desktop_config.json file.

Manual Configuration

Alternatively, you can manually add this configuration (modify the paths as needed):

{
  "mcpServers": {
    "mcp-bauplan": {
      "command": "/path/to/bauplan-mcp-and-skills/.venv/bin/python3",
      "args": [
        "/path/to/bauplan-mcp-and-skills/main.py",
        "--transport",
        "stdio"
      ],
      "workingDirectory": "/path/to/bauplan-mcp-and-skills/"
    }
  }
}

Quit and restart Claude Desktop. Now all Bauplan tools are available to your assistant, as this video demonstrates.

MCP Inspector

Start the MCP Inspector if you wish to manually test the server (Node is required):

npx @modelcontextprotocol/inspector

Now, configure the inspector with the proper variables, e.g. for Streamable HTTP:

• Transport Type: Streamable HTTP
• URL:
• Session Token: Use the token from inspector output

Features

Roadmap

The beta release exposes the core Bauplan functionalities for data lakehouse and pipeline management: thanks to the API-first nature of the platform, a competent AI assistant properly prompted should already be a very effective co-pilot for your lakehouse, including data exploration, schema inspection, iterating on pipelines, etc.

The Bauplan platform is constantly evolving, with new agent-specific commands and fine-grained permissions coming soon. We are now actively improving the MCP server and adding new features, including:

• a server-side deployment option for existing Bauplan users;
• further iterations on MCP and best practices around it for improved code generation (both in co-pilot and in agentic use cases).

If you have specific features you would like to see, please get in touch with us!

Tool List

Data Operations

• **list_tables**: List all tables in a branch/namespace
• **get_schema**: Get schema for all tables in a branch/namespace
• **get_table**: Get schema for a specific table (more efficient for single table)
• **run_query**: Execute SELECT queries on tables
• **run_query_to_csv**: Execute SELECT queries and save results directly to CSV file (scalar data types only)

Branch Management

• **get_branches**: List branches with optional filters
• **get_commits**: Get commit history from branches
• **create_branch**: Create new branches from references
• **has_branch**: Check if a specific branch exists
• **merge_branch**: Merge branches with custom commit messages
• **delete_branch**: Delete branches (with safety checks)

Namespace Management

• **get_namespaces**: List available namespaces in a branch
• **create_namespace**: Create new namespaces in branches
• **has_namespace**: Check if a specific namespace exists in a branch
• **delete_namespace**: Delete namespaces from branches

Tag Management

• **get_tags**: Get tags with optional filters
• **create_tag**: Create a new tag from a reference
• **has_tag**: Check if a tag exists
• **delete_tag**: Delete a tag

Table Management

• **create_table**: Create a table from S3 location using schema detection (creates ICEBERG table structure but doesn't populate data)
• **plan_table_creation**: Create a table import plan from S3 location (generates YAML schema plan with job tracking)
• **apply_table_creation_plan**: Apply a table creation plan to resolve schema conflicts (returns job_id for tracking)
• **has_table**: Check if a specific table exists in a branch/reference
• **delete_table**: Delete a table from a specific branch
• **import_data**: Import data into an existing table from S3 location (returns job_id for tracking)
• **revert_table**: Revert a table from a source reference to a target branch with optional replacement

Project Management

• **project_run**: Run a Bauplan project from a specified directory and reference with configurable parameters (dry-run, timeout, detach mode)
• **code_run**: Run a Bauplan project from code files provided as a dictionary (useful for clients that cannot submit paths), automatically creates temporary directory and validates project structure

Job Management

• **list_jobs**: List jobs in the Bauplan system with optional filtering for all users
• **get_job**: Get detailed information about a specific job by its ID
• **cancel_job**: Cancel a running job by its ID and get updated job status

User Management

• **get_user_info**: Get information about the current authenticated user (username and full name)

Instructions and Guidance

• **get_instructions**: Get detailed instructions for specific Bauplan use cases (pipeline, data, repair, wap, test, sdk)

---

License

This project is provided with no guarantees under the attached MIT License.