Airbyte MCP Server (airbyte-mcp)

MCP server for the Airbyte Public API. Built with the official MCP Python SDK (FastMCP).

Lets any MCP-compatible client (Cursor, Claude Desktop, Claude Code, MCP Inspector, etc.) interact with your Airbyte instance through natural language.

Features

• 30 tools covering workspaces, sources, destinations, connections, jobs, job logs, tags, streams, and connector definitions
• Read and write operations for core resources (create, update, delete)
• Job diagnostics via the internal Configuration API (self-managed): detailed failure reasons, per-stream stats, and structured logs
• Automatic token exchange with in-memory caching and transparent 401 retry
• Markdown and JSON response formats on summary tools; JSON-only for log tools
• Pagination support (limit/offset) on all list tools
• Two transport modes: stdio (local) and streamable HTTP (remote)
• Works with self-managed Airbyte (abctl) and Airbyte Cloud

Available Tools

See docs/endpoints.md for the full Airbyte API endpoint checklist.

Prerequisites

• A running Airbyte instance — either:
• Self-managed via abctl (see docs/local-setup.md)
• Airbyte Cloud
• One of the following to run the server:
• [uv](https://docs.astral.sh/uv/) + Python 3.13+ (local install), or
• [Docker](https://docs.docker.com/get-docker/) (no Python / uv needed on the host)

Quickstart

1. Clone and install

git clone https://github.com/trustxai/airbyte-mcp.git
cd airbyte-mcp
uv sync

2. Configure credentials

cp .env.example .env

For self-managed (abctl), retrieve credentials:

abctl local credentials

Edit .env with your client-id and client-secret. See docs/authentication.md for details.

3. Run the server

#### stdio (Cursor / Claude Desktop / Docker)

uv run airbyte-mcp

#### Streamable HTTP (remote / MCP Inspector)

uv run airbyte-mcp-http
# Listening on http://127.0.0.1:8080/mcp

Client Configuration

Every MCP client (Cursor, Claude Desktop, etc.) can run the server in one of two ways:

• uv — quickest to set up, but requires uv installed locally.
• Docker — no Python / uv required on the host; everything runs in a container. Build the image once and every client config reuses it.

Host networking note: if Airbyte is running on your host machine (e.g. via abctl), inside the Docker container localhost does not point to your host. Use http://host.docker.internal:8000/api/public/v1 on macOS/Windows, or add --network=host to the docker run args on Linux.

Build the Docker image (one-time)

docker build -t airbyte-mcp:latest .

Cursor

Add to .cursor/mcp.json (project-level) or ~/.cursor/mcp.json (global):

Option A — uv

{
  "mcpServers": {
    "airbyte": {
      "command": "uv",
      "args": ["--directory", "/path/to/airbyte-mcp", "run", "airbyte-mcp"],
      "env": {
        "AIRBYTE_API_URL": "http://localhost:8000/api/public/v1",
        "AIRBYTE_CLIENT_ID": "<your-client-id>",
        "AIRBYTE_CLIENT_SECRET": "<your-client-secret>"
      }
    }
  }
}

Option B — Docker

{
  "mcpServers": {
    "airbyte": {
      "command": "docker",
      "args": [
        "run", "--rm", "-i",
        "--name", "airbyte-mcp",
        "-e", "AIRBYTE_API_URL",
        "-e", "AIRBYTE_CLIENT_ID",
        "-e", "AIRBYTE_CLIENT_SECRET",
        "airbyte-mcp:latest"
      ],
      "env": {
        "AIRBYTE_API_URL": "http://host.docker.internal:8000/api/public/v1",
        "AIRBYTE_CLIENT_ID": "<your-client-id>",
        "AIRBYTE_CLIENT_SECRET": "<your-client-secret>"
      }
    }
  }
}

Claude Desktop

Add to claude_desktop_config.json:

Option A — uv

{
  "mcpServers": {
    "airbyte": {
      "command": "uv",
      "args": ["--directory", "/path/to/airbyte-mcp", "run", "airbyte-mcp"],
      "env": {
        "AIRBYTE_API_URL": "http://localhost:8000/api/public/v1",
        "AIRBYTE_CLIENT_ID": "<your-client-id>",
        "AIRBYTE_CLIENT_SECRET": "<your-client-secret>"
      }
    }
  }
}

Option B — Docker

{
  "mcpServers": {
    "airbyte": {
      "command": "docker",
      "args": [
        "run", "--rm", "-i",
        "--name", "airbyte-mcp",
        "-e", "AIRBYTE_API_URL",
        "-e", "AIRBYTE_CLIENT_ID",
        "-e", "AIRBYTE_CLIENT_SECRET",
        "airbyte-mcp:latest"
      ],
      "env": {
        "AIRBYTE_API_URL": "http://host.docker.internal:8000/api/public/v1",
        "AIRBYTE_CLIENT_ID": "<your-client-id>",
        "AIRBYTE_CLIENT_SECRET": "<your-client-secret>"
      }
    }
  }
}

Claude Code (HTTP)

Option A — uv

uv run airbyte-mcp-http &
claude mcp add --transport http airbyte http://127.0.0.1:8080/mcp

Option B — Docker

docker build -f Dockerfile.http -t airbyte-mcp-http:latest .
docker run -d --rm --name airbyte-mcp-http \
  -p 8080:8080 \
  -e AIRBYTE_API_URL=http://host.docker.internal:8000/api/public/v1 \
  -e AIRBYTE_CLIENT_ID=<your-client-id> \
  -e AIRBYTE_CLIENT_SECRET=<your-client-secret> \
  airbyte-mcp-http:latest
claude mcp add --transport http airbyte http://127.0.0.1:8080/mcp

MCP Inspector

# Start the server in HTTP mode (uv or docker — either works)
uv run airbyte-mcp-http
#   or: docker run --rm -p 8080:8080 --env-file .env airbyte-mcp-http:latest

# In another terminal
npx @modelcontextprotocol/inspector
# Then connect to http://127.0.0.1:8080/mcp in the inspector UI

Running Manually (without a client)

If you just want to exercise the server from the CLI:

# stdio (uv)
uv run airbyte-mcp

# stdio (Docker)
docker run --rm -i --env-file .env airbyte-mcp:latest

# HTTP (uv)
uv run airbyte-mcp-http

# HTTP (Docker)
docker run --rm -p 8080:8080 --env-file .env airbyte-mcp-http:latest

Environment Variables

*Not required if AIRBYTE_ACCESS_TOKEN is provided.

Documentation

• Authentication — token exchange, credentials setup
• Architecture — system design, package layout, token lifecycle
• Endpoints Checklist — full Airbyte API coverage status
• Local Setup — abctl installation walkthrough
• Contributing — development workflow, PR guidelines
• Security — vulnerability reporting
• Changelog — release history

Contributing

Contributions are welcome! See docs/CONTRIBUTING.md to get started.

License

Apache-2.0 — see LICENSE for details.