airbyte-mcp 0.2.0

MCP server for the Airbyte Public API (self-managed / Cloud).

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

• 11 read-only tools covering workspaces, sources, destinations, connections, and jobs
• Automatic token exchange with in-memory caching and transparent 401 retry
• Markdown and JSON response formats on every tool
• 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

Tool	Description
airbyte_health_check	Ping the Airbyte API
airbyte_list_workspaces	List workspaces with pagination
airbyte_get_workspace	Get workspace details by ID
airbyte_list_sources	List source connectors (filter by workspace)
airbyte_get_source	Get source details by ID
airbyte_list_destinations	List destination connectors (filter by workspace)
airbyte_get_destination	Get destination details by ID
airbyte_list_connections	List connections / pipelines (filter by workspace)
airbyte_get_connection	Get connection details including stream config
airbyte_list_jobs	List jobs (filter by connection, type, status, dates)
airbyte_get_job	Get job details (status, duration, bytes/rows synced)

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 + Python 3.13+ (local install), or
  • 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

Variable	Required	Default	Description
AIRBYTE_API_URL	No	http://localhost:8000/api/public/v1	Airbyte API base URL
AIRBYTE_CLIENT_ID	Yes*	—	Application client ID
AIRBYTE_CLIENT_SECRET	Yes*	—	Application client secret
AIRBYTE_ACCESS_TOKEN	No	—	Pre-fetched token (skips exchange)
HTTP_HOST	No	127.0.0.1	HTTP transport bind address
HTTP_PORT	No	8080	HTTP transport port

*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.