Skip to main content
Glama
airbyte-oss-mcp

airbyte-oss-mcp

by NGRThomson

Airbyte OSS MCP

Read-only MCP server for self-hosted Airbyte OSS 1.6.x.

Wraps:

  • Public API — /api/public/v1 (connections, jobs, health)

  • Internal API — /api/v1/jobs/get_without_logs (attempt failure summaries)

Modeled after dagster-mcp (FastMCP + env-based config).

Install (Cursor + uvx)

Prerequisites: uv installed, network access to your Airbyte instance.

Add to ~/.cursor/mcp.json:

{
  "mcpServers": {
    "airbyte": {
      "command": "uvx",
      "args": [
        "--from",
        "git+https://github.com/NGRThomson/airbyte-oss-mcp.git@main",
        "airbyte-mcp"
      ],
      "env": {
        "AIRBYTE_URL": "https://airbyte.example.com",
        "AIRBYTE_READ_ONLY": "true"
      }
    }
  }
}

Replace AIRBYTE_URL with your instance URL. Default (if unset) is http://localhost:8000.

Pin a tag or commit for slower upgrades:

git+https://github.com/NGRThomson/airbyte-oss-mcp.git@v0.3.0

See examples/cursor-mcp.json for a team install template.

Optional persistent install:

uv tool install --from 'git+https://github.com/NGRThomson/airbyte-oss-mcp.git@main' airbyte-mcp

Local dev

"args": ["--from", "/path/to/airbyte-oss-mcp", "airbyte-mcp"]

Or:

cd airbyte-oss-mcp
uv sync --extra dev
uv run ruff check airbyte_mcp/
uv run pytest
uv run airbyte-mcp

Related MCP server: airflow-mcp-server

Environment variables

Variable

Default

Purpose

AIRBYTE_URL

http://localhost:8000

Base URL of your Airbyte instance

AIRBYTE_API_TOKEN

(empty)

Bearer token if public API auth is enabled

AIRBYTE_READ_ONLY

true

When false, exposes cancel_job and trigger_sync

AIRBYTE_ENVS

(empty)

JSON map of named envs for multi-instance setups

AIRBYTE_DEFAULT_ENV

(empty)

Default key when AIRBYTE_ENVS has multiple entries

Multi-env example:

"AIRBYTE_ENVS": "{\"prod\":{\"url\":\"https://airbyte.example.com\"},\"staging\":{\"url\":\"https://airbyte-staging.example.com\"}}",
"AIRBYTE_DEFAULT_ENV": "prod"

Optional bearer token:

"AIRBYTE_API_TOKEN": "<token from Airbyte Settings → Applications>"

Tools

Tool

Purpose

get_instance_status

Health, connection counts, running/pending/failed job counts (bounded samples)

list_connections

Browse/filter connections

get_connection

One connection + recent jobs

list_jobs

Recent jobs (filter by connection/status)

get_job

Public job metadata

get_job_details

Attempt stats + failure summaries

get_job_failure_summary

Root-cause failure messages for a failed sync

Write tools (cancel_job, trigger_sync) register only when AIRBYTE_READ_ONLY=false.

Smoke test

uv run python -c "
from airbyte_mcp.client import AirbyteClient
c = AirbyteClient('https://airbyte.example.com')
print(c.health())
print('running', len(c.list_jobs(status='running', limit=10)))
"

Notes

  • Always pass orderBy=updatedAt|DESC when listing jobs (default in client) — otherwise Airbyte returns oldest jobs first.

  • Raw job logs are not exposed (public API has no log endpoint); failure summaries come from internal get_without_logs.

  • Internal OSS API: get_job_details and get_job_failure_summary use /api/v1/jobs/get_without_logs, which is not part of the public API and may break on Airbyte upgrades.

  • list_connections / list_jobs paginate automatically when limit exceeds the API page size (100).

  • Runtime data: when pointed at a live instance, tool responses include connection names, job errors, and IDs from your Airbyte workspace — keep MCP read-only in shared Cursor configs if that metadata is sensitive.

Available Tools

9 tools
find_duplicate_destination_tablesA

Detect multiple active connections writing the same BigQuery project.dataset.table.

Best-effort audit using connection stream config and destination settings. Skips non-BigQuery destinations and inactive connections.

Inputs: env. Returns: object

get_active_syncsB

List all currently running sync jobs with connection names.

Best tool to answer 'what is blocking the Airbyte worker pool?' or 'why is this sync taking so long?'

Inputs: env. Returns: result

get_connectionA

Get one connection by exact name or connectionId UUID.

Returns connection metadata with stream summaries (name, namespace, prefix, syncMode) and the three most recent sync jobs.

Inputs: connection (required), env. Returns: object

get_instance_statusA

Global Airbyte health snapshot. Start here for monitoring workflows.

Returns health text, workspace count, connection counts by status, and counts of running / pending / failed sync jobs (recent sample).

Inputs: env. Returns: object

get_jobC

Get public job metadata for a sync job id.

Inputs: job_id (required), env. Returns: object

get_job_detailsA

Get job plus attempt stats via the internal OSS jobs API.

Includes per-attempt totalStats and failure summaries (without raw logs).

Inputs: job_id (required), env. Returns: object

get_job_failure_summaryA

Consolidated failure diagnosis for a sync job (prefer over raw logs).

Returns root-cause failure messages from the latest failed attempt, plus job/connection context and row/byte stats when available.

Inputs: job_id (required), env. Returns: object

list_connectionsA

List Airbyte connections with schedule and status metadata.

Filters:

  • name_prefix: case-insensitive substring on connection name

  • status: exact status filter (e.g. 'active')

  • limit: max results (paginates beyond the 100-item API page size when needed)

  • offset: skip first N connections from the API ordering

Inputs: name_prefix, status, limit, offset, +1 more. Returns: result

list_jobsA

List recent sync jobs, newest first.

Returns jobId, status, startTime, duration, bytesSynced, rowsSynced, connectionId, and connectionName.

Filters:

  • connection: connection name, UUID, or substring (must match exactly one)

  • status: pending, running, incomplete, failed, succeeded, cancelled

  • limit: max results (paginates beyond the 100-item API page size when needed)

  • offset: skip first N jobs from the API ordering

Inputs: connection, status, limit, offset, +1 more. Returns: result

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    B3.3/5.0

    Scored across 9 tools

    Disambiguation3/5

    Tools are mostly distinct, but there is overlap among get_job, get_job_details, and get_job_failure_summary, which could confuse an agent about which to use. Additionally, get_active_syncs overlaps with list_jobs filtered by status. Descriptions help but ambiguity remains.

    Naming Consistency4/5

    Most tools follow a 'get_' or 'list_' pattern, but get_active_syncs uses 'get' for a list operation and find_duplicate_destination_tables uses 'find_', which is a minor deviation from the prevailing pattern.

    Tool Count5/5

    With 9 tools, the server is well-scoped for its intended purpose of monitoring and auditing Airbyte instances. Each tool has a clear role and no unnecessary redundancy.

    Completeness2/5

    The tool set is heavily biased towards read and monitoring operations, missing essential CRUD capabilities like creating or updating connections and triggering syncs. This leaves significant gaps for a full Airbyte management server.

    Maintenance

    ActivityNo data
    ResponsivenessOutdated data

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      B
      quality
      D
      maintenance
      A read-only MCP server for OpenObserve Community Edition that works over the REST API. Provides tools for searching logs, traces, stream schemas, and dashboards - no Enterprise license required.
      8
      68 PyPI
      16
      GPL 3.0
    • F
      license
      Not graded
      quality
      D
      maintenance
      Read-only MCP server for Hevo Data API, enabling monitoring of pipelines, objects, destinations, models, and workflows with secure self-hosted credentials.
      -