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.2.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: openobserve-community-mcp

Environment variables

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

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.