--- slug: "bauplan-mcp-server" source_type: "readme" source_url: "https://cdn.jsdelivr.net/gh/BauplanLabs/bauplan-mcp-server@main/README.md" repo: "https://github.com/BauplanLabs/bauplan-mcp-server" source_file: "README.md" branch: "main" --- # Bauplan MCP Server A Model Context Protocol (MCP) 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](https://www.loom.com/share/651e2bd7ad4442928f539859a621c562) demonstrates setup and usage. > [!NOTE] > This project is released in Beta under MIT license. APIs and features may change without notice as we continue development. > [!IMPORTANT] > **A hosted MCP server is now available** for existing Bauplan users at `https://mcp.use1.aprod.bauplanlabs.com/mcp` - you no longer need to run the server locally. Add it as a custom connector in Claude Desktop (or any MCP client) and authenticate with your Bauplan API key. See [Execution modes](#execution-modes) for all the ways to run the server. ## Overview This repository contains the Bauplan MCP Server — a Model Context Protocol server that gives AI assistants access to Bauplan lakehouse operations. A blog post with context and background [is available here](https://www.bauplanlabs.com/post/bauplans-mcp-server). > [!TIP] > **Looking for the best local AI setup with Bauplan?** Check out **[BauplanLabs/bauplan-skills](https://github.com/BauplanLabs/bauplan-skills)** — it includes agent playbooks (`CLAUDE.md`), skills, and everything you need to get AI coding assistants working with Bauplan via CLI and SDK, without running an MCP server. ## Execution modes The server supports three execution modes. They differ in who runs the server and in which tools are exposed: tool visibility is set by [FastMCP tags](#container-runtime) and can be tuned with `MCP_VISIBLE_TOOL_TAGS`. All three authenticate with your Bauplan API key. 1. **Local** - run the server on your own machine and point your AI assistant at `http://localhost:8000/mcp`; exposes every tool by default. See [MCP Quick Start](#mcp-quick-start). 2. **Self-hosted** - deploy the server on your own infrastructure and point your assistant at your endpoint, passing your Bauplan API key as a bearer token; control the exposed tools with `MCP_VISIBLE_TOOL_TAGS`. See [Bauplan Credentials](#bauplan-credentials) and [Container Runtime](#container-runtime). 3. **Bauplan public endpoint** - skip running a server and connect directly to Bauplan's hosted endpoint at `https://mcp.use1.aprod.bauplanlabs.com/mcp`; exposes only the remote-safe tools. ## 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](https://drive.google.com/file/d/1BIBBuxuCKrrHvxOfkut_8TuYy77HZ1rQ/view?usp=sharing) for reference. You need: * a Bauplan [API key](https://app.bauplanlabs.com/sign-up) properly configured in your local config file (default profile) - the server will pick it up automatically (see below for alternative authentication methods); * [uv](https://docs.astral.sh/uv/guides/install-python/) (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: ```bash 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: ```bash claude mcp add -t http mcp-bauplan http://localhost:8000/mcp ``` Similar commands can be run on [Claude Desktop](https://modelcontextprotocol.io/quickstart/user) or [Cursor](https://docs.cursor.com/en/context/mcp) 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!). ## 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 - either `Authorization: Bearer ` or `Bauplan: ` (e.g. in Claude Code `claude mcp add -H "Authorization: Bearer " ...`) -, that value 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. For example, if you are connecting to a remotely hosted MCP server that delegates Bauplan authentication to the client, you can register it in Claude Code and pass your own bearer token with: ```bash claude mcp add -t http -H "Authorization: Bearer " mcp-bauplan https:///mcp ``` ### Server CLI Options The server supports the following CLI options, mostly useful for specifying alternative transport options: | Option | Default | Description | Used With | |---------------|-------------|----------------------------------------------------------|-------------------------------| | `--transport` | `stdio` | Transport protocol: `stdio`, `sse`, or `streamable-http` | All commands | | `--host` | `127.0.0.1` | Host to bind to (localhost by default) | `sse`, `streamable-http` only | | `--port` | `8000` | Port to bind to | `sse`, `streamable-http` only | | `--profile` | `None` | Bauplan profile to use | All commands | **Note:** The `--host` and `--port` options are ignored when using `stdio` transport since it communicates through stdin/stdout. ### Container Runtime The Docker image starts HTTP transports with Gunicorn and Uvicorn workers. This is meant for remote deployments where several requests can be handled concurrently. Local MCP usage should continue to use `python main.py`, especially for `stdio`. Useful environment variables: | Variable | Default | Description | |------------------|-------------------|--------------------------------------------------| | `MCP_TRANSPORT` | `streamable-http` | HTTP transport for the container, or `stdio` | | `MCP_WORKERS` | `4` | Gunicorn worker count for HTTP transports | | `MCP_KEEP_ALIVE` | `65` | Gunicorn keep-alive timeout in seconds | | `PORT` | `8000` | Container listen port for HTTP transports | | `MCP_AUTH_MODE` | `none` | Use `api-key-oauth` for remote OAuth clients | | `MCP_PUBLIC_BASE_URL` | required for OAuth | Public MCP server base URL. Requires `MCP_AUTH_MODE=api-key-oauth` | | `MCP_LOG_TOOL_ARGS` | `false` | Log full tool arguments for debugging. Emits a warning when `MCP_PUBLIC_BASE_URL` is set | | `MCP_VISIBLE_TOOL_TAGS` | unset locally, `remote` in OAuth mode | Comma-separated allowlist of FastMCP tool tags to expose | | `MCP_OAUTH_SECRET` | required for OAuth | Stable secret used to sign tokens and encrypt API keys | | `MCP_OAUTH_TRUSTED_REDIRECTS` | Claude and ChatGPT callbacks | Comma-separated trusted redirect list. Supports a trailing `*` for trusted path prefixes | Tool visibility is controlled with FastMCP tags. Local runs expose every tool by default. Remote OAuth runs expose only tools tagged `remote` unless `MCP_VISIBLE_TOOL_TAGS` is set explicitly. This keeps local-only tools such as `project_run` and `run_query_to_csv` out of shared server deployments. When multiple tags are configured, a tool is visible if it has at least one matching tag. Useful examples: ```bash # Expose only remote-safe tools. MCP_VISIBLE_TOOL_TAGS=remote uv run python main.py --transport streamable-http # Expose only read-only tools for inspection. MCP_VISIBLE_TOOL_TAGS=read uv run python main.py --transport streamable-http ``` Current tags are `remote`, `local`, `read`, `write`, and `destructive`. OAuth clients with valid HTTPS redirect URIs can still register dynamically. Redirects outside `MCP_OAUTH_TRUSTED_REDIRECTS` are shown to users as unverified before they continue. ### Claude Desktop To add the Bauplan MCP server to Claude Desktop, follow the [guide](https://modelcontextprotocol.io/quickstart/user) to get to your `claude_desktop_config.json` file. You can then add this configuration (modify the paths as needed): ```json { "mcpServers": { "mcp-bauplan": { "command": "/path/to/bauplan-mcp-server/.venv/bin/python3", "args": [ "/path/to/bauplan-mcp-server/main.py", "--transport", "stdio" ], "workingDirectory": "/path/to/bauplan-mcp-server/" } } } ``` Quit and restart Claude Desktop. Now all Bauplan tools are available to your assistant, as this [video](https://www.loom.com/share/5eb09b3c30cc4cd984fb1ba21a70f349?sid=9e70c948-77e5-4cb0-b487-0db3adedf919) demonstrates. ### MCP Inspector Start the [MCP Inspector](https://github.com/modelcontextprotocol/inspector) if you wish to manually test the server (Node is required): ```bash 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 ### Tool List #### Data Operations * **`get_tables`**: List 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 (local/non-OAuth servers only, scalar data types only) #### Branch Management * **`get_branches`**: List branches with optional filters * **`get_branch`**: Get a branch by name * **`get_commits`**: Get commit history from branches * **`create_branch`**: Create new branches from references * **`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 * **`get_namespace`**: Get a namespace by name * **`create_namespace`**: Create new namespaces in branches * **`delete_namespace`**: Delete namespaces from branches #### Tag Management * **`get_tags`**: Get tags with optional filters * **`get_tag`**: Get a tag by name * **`create_tag`**: Create a new tag from a reference * **`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) * **`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 (local/non-OAuth servers only) * **`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 * **`get_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.