Airbyte Oss

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/[email protected]

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

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.