airbyte-oss-mcp
The airbyte-oss-mcp server provides read-only monitoring and diagnostic tools for self-hosted Airbyte OSS instances, with optional write capabilities.
get_instance_status— Get a global health snapshot including workspace count, connection counts by status, and running/pending/failed job counts.list_connections— Browse and filter connections by name prefix or status, with automatic pagination beyond the default 100-item API page size.get_connection— Retrieve detailed metadata for a single connection (by name or UUID), including stream summaries and the three most recent sync jobs.list_jobs— List recent sync jobs (newest first), filterable by connection and status, with fields like jobId, status, duration, and bytes/rows synced.get_active_syncs— See all currently running sync jobs with connection names — useful for diagnosing worker pool bottlenecks.get_job— Fetch public metadata for a specific sync job by ID.get_job_details— Retrieve detailed job and attempt stats via the internal OSS API, including per-attempt statistics and failure summaries.get_job_failure_summary— Get a consolidated root-cause failure diagnosis for a failed sync job, including job/connection context and row/byte stats.find_duplicate_destination_tables— Detect multiple active connections writing to the same BigQuery project/dataset/table to identify potential data overwrite issues.Multi-environment support — All tools accept an optional
envparameter to query multiple named Airbyte instances configured viaAIRBYTE_ENVSandAIRBYTE_DEFAULT_ENV.Optional write tools —
cancel_jobandtrigger_syncare available whenAIRBYTE_READ_ONLY=false(disabled by default).
Provides tools for interacting with a self-hosted Airbyte OSS instance, including checking health, listing connections and jobs, retrieving job details and failure summaries, and optionally triggering syncs or canceling jobs.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@airbyte-oss-mcp show me the current health and active syncs"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
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.0See 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-mcpLocal 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-mcpRelated MCP server: airflow-mcp-server
Environment variables
Variable | Default | Purpose |
|
| Base URL of your Airbyte instance |
| (empty) | Bearer token if public API auth is enabled |
|
| When false, exposes |
| (empty) | JSON map of named envs for multi-instance setups |
| (empty) | Default key when |
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 |
| Health, connection counts, running/pending/failed job counts (bounded samples) |
| Browse/filter connections |
| One connection + recent jobs |
| Recent jobs (filter by connection/status) |
| Public job metadata |
| Attempt stats + failure summaries |
| 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|DESCwhen 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_detailsandget_job_failure_summaryuse/api/v1/jobs/get_without_logs, which is not part of the public API and may break on Airbyte upgrades.list_connections/list_jobspaginate automatically whenlimitexceeds 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 toolsfind_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
Scored across 9 tools
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.
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.
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.
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
Related MCP Connectors
Read-only MCP server for AIStatusDashboard status, incidents, metrics, and fallback recommendations.
Official Airtable MCP server — database and operations layer for agents.
MCP server that lets AI assistants use all OneSchema features exposed via the public API.
Read-only MCP server for public WeJob jobs, formations, and companies.
Related MCP Servers
- AlicenseBqualityDmaintenanceA 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.868 PyPI16GPL 3.0
- AlicenseAqualityCmaintenanceAirflow MCP server — read DAGs, runs, task instances, log tails; trigger and clear (write-gated).861 npm2MIT
- AlicenseAqualityBmaintenanceRead-only MCP server for safe Kubernetes inspection, diagnosis, and debugging. Supports Kubernetes core, Helm, Argo Workflows, and Argo CD.2174 npm5MIT
- FlicenseNot gradedqualityDmaintenanceRead-only MCP server for Hevo Data API, enabling monitoring of pipelines, objects, destinations, models, and workflows with secure self-hosted credentials.-