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

• 36 tools covering workspaces, sources, destinations, connections, jobs, refresh/clear, 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

• Cloud full-text sync logs via airbyte_get_cloud_sync_logs (Airbyte Cloud only; parity with official Replication MCP)

• 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

• Runs over stdio (local) — works with Cursor, Claude Desktop, Claude Code, and Docker

• Works with self-managed Airbyte (abctl) and Airbyte Cloud

Related MCP server: Airflow MCP

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:

  • uvx (zero-install; runs the published package on demand — see Run with uvx), or

  • uv + Python 3.13+ (local clone / development), 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

uv run airbyte-mcp

Run with uvx (zero-install)

uvx runs the published PyPI package on demand — no clone, no virtualenv, no persistent install. The command matches the package name, so no --from is needed:

uvx airbyte-mcp

Not the same as the official Airbyte replication MCP. That one lives in the airbyte package and is invoked as uvx --from=airbyte@latest airbyte-mcp. Here the PyPI package is airbyte-mcp, so uvx airbyte-mcp unambiguously resolves to this server.

Credentials are passed via the client's env block (see below), or exported in your shell for a manual run:

AIRBYTE_API_URL=http://localhost:8000/api/public/v1 \
AIRBYTE_CLIENT_ID=<your-client-id> \
AIRBYTE_CLIENT_SECRET=<your-client-secret> \
uvx airbyte-mcp

Python version: the package targets Python 3.13+. uv auto-provisions a matching interpreter, so this normally just works. If your environment pins an older default, force it with uvx --python=3.13 airbyte-mcp.

Client config (e.g. Cursor .cursor/mcp.json) using uvx:

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

Client Configuration

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

• uvx — zero-install; runs the published package on demand (see Run with uvx).

• uv — from a local clone; best for development.

• 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

claude mcp add \
  --env AIRBYTE_API_URL=http://localhost:8000/api/public/v1 \
  --env AIRBYTE_CLIENT_ID=<your-client-id> \
  --env AIRBYTE_CLIENT_SECRET=<your-client-secret> \
  --transport stdio \
  airbyte \
  -- uvx airbyte-mcp

MCP Inspector

The Inspector can launch the stdio server directly:

npx @modelcontextprotocol/inspector uvx airbyte-mcp

Set AIRBYTE_API_URL, AIRBYTE_CLIENT_ID, and AIRBYTE_CLIENT_SECRET in the Inspector's environment panel (or export them in your shell first).

Running Manually (without a client)

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

# uvx — no clone
uvx airbyte-mcp

# uv
uv run airbyte-mcp

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

Environment Variables

*Not required if AIRBYTE_ACCESS_TOKEN is provided.

Documentation

• Authentication — token exchange, credentials setup

• Architecture — system design, package layout, token lifecycle

• Comparison vs Official MCPs — open-source-first positioning vs official MCPs

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