MCP Bauplan

🚀 mcp-bauplan

A minimalist Model Context Protocol (MCP) server for interacting with data tables and running Bauplan queries.

Bauplan manages the data storage of Iceberg tables in the configured namespace on S3.

✨ Features

• Retrieve all Bauplan data tables and their schemas in the configured namespace.
• Execute queries on specified tables using SQL (SELECT only).

It supports both SSE and STDIO transmission methods.

🛠️ Tools

The server implements the following tools to interact with Bauplan data tables:

• list_tables:
  • List all tables in the configured namespace.
• get_schema:
  • Get the schema of a specified data table.
• run_query:
  • Execute a SELECT query on a specified table.

⚙️ Configuration

1. Create or edit the Claude desktop configuration file located at:

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
• Windows: %APPDATA%/Claude/claude_desktop_config.json

2. Add the following content:

{
  "mcpServers": {
    "mcp-bauplan": {
      "command": "/path/to/uvx",
      "args": ["mcp-bauplan"],
      "env": {
        "BAUPLAN_API_KEY": "your-api-key",
        "BAUPLAN_BRANCH": "your-branch",
        "BAUPLAN_NAMESPACE": "your-namespace",
        // Optional
        "BAUPLAN_TIMEOUT": "query-timeout-secs" // Default is 30 seconds
      }
    }
  }
}

3. Replace /path/to/uvx with the absolute path of the uvx executable file. Use the which uvx command in the terminal to find the path. This ensures that the correct version of uvx is used when starting the server.

4. Restart the Claude desktop to apply the changes.

🚀 Running an Independent SSE Server

Create a .env file from .env.example, then execute the following command:

$ uvx --env-file /path/to/.env mcp-bauplan --transport sse --port 9090

⚠️ Important Note

Using nvx instead of uvx will fetch mcp-bauplan from the default repository https://pypi.org.

💻 Development

⚙️ Setup

1. Prerequisites:

• Python 3.10 or higher.
• Bauplan API key (request here).
• uv package manager (install here).

2. Clone the repository:

git clone https://github.com/marcoeg/mcp-bauplan
cd mcp-nvd

3. Set environment variables:

• Create a .env file in the project root directory:

  BAUPLAN_API_KEY=your-api-key
  BAUPLAN_BRANCH=your-branch
  BAUPLAN_NAMESPACE=your-namespace
  

4. Install dependencies:

uv sync
uv pip install -e .

🏃‍♂️ Running with MCP Inspector

cd /path/to/the/repo
source .env

CLIENT_PORT=8077 SERVER_PORT=8078 npx @modelcontextprotocol/inspector \
     uv run mcp-bauplan

⚠️ Important Note

If the standard ports do not conflict, omit CLIENT_PORT=8077 SERVER_PORT=8078.

Then open the indicated URL in the browser, usually http://localhost:8077?proxyPort=8078

💡 Usage Tip

You can freely switch between stdio and sse transmission types in the inspector. To use sse, run the server as described below.

🧪 Testing with SSE Transmission

🏃‍♂️ Run the server:

cd /path/to/the/repo
source .env

uv run mcp-bauplan --transport sse --port 9090

• By default, it runs on port 9090 using SSE transmission.

Then open the indicated URL in the browser and select the SSE transmission type.