airbyte.mcp

Airbyte Replication MCP Server - Model Context Protocol Integration

NOTE: This MCP server implementation is experimental and may change without notice between minor versions of PyAirbyte. The API may be modified or entirely refactored in future versions.

The Airbyte Replication MCP (Model Context Protocol) server provides a standardized interface for managing Airbyte connectors through MCP-compatible clients. This PyAirbyte-powered experimental feature allows you to list connectors, validate configurations, and run sync operations using the MCP protocol.

Getting Started with Airbyte Replication MCP

To get started with the Airbyte Replication MCP server, follow these steps:

Create a Dotenv secrets file.
Register the MCP server with your MCP client.
Test the MCP server connection using your MCP client.

Step 1: Generate a Dotenv Secrets File

To get started with the Airbyte Replication MCP server, you will need to create a dotenv file containing your Airbyte Cloud credentials, as well as credentials for any third-party services you wish to connect to via Airbyte.

Create a file named ~/.mcp/airbyte_mcp.env with the following content:

# Airbyte Project Artifacts Directory
AIRBYTE_PROJECT_DIR=/path/to/any/writeable/project-dir

# Airbyte Cloud Credentials (Required for Airbyte Cloud Operations)
AIRBYTE_CLOUD_CLIENT_ID=your_api_key
AIRBYTE_CLOUD_CLIENT_SECRET=your_api_secret
AIRBYTE_CLOUD_WORKSPACE_ID=your_workspace_id

# API-Specific Credentials (Optional, depending on your connectors)

# For example, for a PostgreSQL source connector:
# POSTGRES_HOST=your_postgres_host
# POSTGRES_PORT=5432
# POSTGRES_DB=your_database_name
# POSTGRES_USER=your_database_user
# POSTGRES_PASSWORD=your_database_password

# For example, for a Stripe source connector:
# STRIPE_API_KEY=your_stripe_api_key
# STRIPE_API_SECRET=your_stripe_api_secret
# STRIPE_WEBHOOK_SECRET=your_stripe_webhook_secret

Note:

You can add more environment variables to this file as needed for different connectors. To start, you only need to create the file and pass it to the MCP server.
Ensure that this file is kept secure, as it contains sensitive information. Your LLM should never be given direct access to this file or its contents.
The MCP tools will give your LLM the ability to view which variables are available, but it does not give access to their values.
The AIRBYTE_PROJECT_DIR variable specifies a directory where the MCP server can store temporary project files. Ensure this directory is writable by the user running the MCP server.

Step 2: Registering the MCP Server

First install uv (brew install uv).

Then, create a file named server_config.json (or the file name required by your MCP client) with the following content. This uses uvx (from brew install uv) to run the MCP server. If a matching version Python is not yet installed, a uv-managed Python version will be installed automatically. This will also auto-update to use the "latest" Airbyte MCP release at time of launch. You can alternatively pin to a specific version of Python and/or of the Airbyte library if you have special requirements.

{
  "mcpServers": {
    "airbyte": {
      "command": "uvx",
      "args": [
        "--python=3.11",
        "--from=airbyte@latest",
        "airbyte-mcp"
      ],
      "env": {
        "AIRBYTE_MCP_ENV_FILE": "/path/to/my/.mcp/airbyte_mcp.env",
        "AIRBYTE_CLOUD_MCP_SAFE_MODE": "1",
        "AIRBYTE_CLOUD_MCP_READONLY_MODE": "0"
      }
    }
  }
}

Note:

Replace /path/to/my/.mcp/airbyte_mcp.env with the absolute path to your dotenv file created in Step 1.

Step 3: Testing the MCP Server Connection

You can test the MCP server connection using your MCP client.

Helpful prompts to try:

"Use your MCP tools to list all available Airbyte connectors."
"Use your MCP tools to get information about the Airbyte Stripe connector."
"Use your MCP tools to list all variables you have access to in the dotenv secrets file."
"Use your MCP tools to check your connection to your Airbyte Cloud workspace."
"Use your MCP tools to list all available destinations in my Airbyte Cloud workspace."

Airbyte Cloud MCP Server Safety

The Airbyte Replication MCP server supports environment variables to control safety and access levels for Airbyte Cloud operations.

Important: The below settings only affect Cloud operations; local operations are not affected.

Airbyte Cloud Safe Mode

Safe mode is enabled by default and is controlled by the AIRBYTE_CLOUD_MCP_SAFE_MODE environment variable.

When enabled, write operations are allowed but destructive operations (updates, deletions) are only allowed for objects created within the same session. For example, you can create a new connector and then delete it, but you cannot delete an existing connector that was not created in the current session. Modifications to configurations are likewise treated as potentially destructive and are only allowed for objects created in the current session.

Set the environment variable AIRBYTE_CLOUD_MCP_SAFE_MODE=0 to disable safe mode.

Airbyte Cloud Read-Only Mode

Read-only mode is not enabled by default and is controlled by the AIRBYTE_CLOUD_MCP_READONLY_MODE environment variable.

When enabled, only read-only Cloud tools are available. Write and destructive operations are disabled.

This mode does allow running syncs on existing connectors, since sync operations are not considered to be modifications of the Airbyte Cloud workspace.

Set the environment variable AIRBYTE_CLOUD_MCP_READONLY_MODE=1 to enable read-only mode.

Authentication for Remote (HTTP) Servers

The steps above run the MCP server over stdio — the client launches the server process locally, so there is no transport-layer auth and the only credentials that matter are your Airbyte Cloud creds in the dotenv file.

When the server is instead exposed over HTTP (airbyte-mcp-http / poe mcp-serve-http), it verifies an Authorization: Bearer <token> on every request. Two client shapes are supported on the same deployment (combined automatically when both are configured):

Humans → interactive OIDC

Set OIDC_CONFIG_URL, OIDC_CLIENT_ID, and OIDC_CLIENT_SECRET. Interactive clients open a browser (Keycloak Authorization Code + PKCE) and the resulting token is verified by the server. No bearer token to manage by hand.

Machines / agents → headless bearer token

There is no transport mode that accepts a raw client_id + client_secret in a header. A headless agent mints its own short-lived bearer token and sends it as Authorization: Bearer <token>; the server verifies the signature (no browser, no stored/rotating refresh token).

For Airbyte Cloud, set MCP_AUTH_AIRBYTE_CLOUD=true on the server so it verifies tokens against Airbyte Cloud's application-client realm without hand-configuring URLs. The agent mints an Airbyte Cloud access token from its AIRBYTE_CLOUD_CLIENT_ID / AIRBYTE_CLOUD_CLIENT_SECRET (the https://api.airbyte.com/v1/applications/token endpoint) and sends it as the bearer. That single token both authenticates transport (verified by the server) and authorizes downstream Cloud API calls, because an Airbyte-Cloud-issued token is itself a valid Cloud API bearer. Tokens are short-lived (~15 min), so re-mint on expiry / on a 401 rather than pinning a static token.

Clients that support HTTP transports can pass the token via a headers block in their MCP config:

{
  "mcpServers": {
    "airbyte": {
      "url": "https://<host>/mcp",
      "headers": {
        "Authorization": "Bearer ${AIRBYTE_MCP_TOKEN}"
      }
    }
  }
}

Server environment variables (HTTP mode)

MCP_SERVER_URL — public base URL of the server (also used for OIDC redirect callbacks); defaults to http://localhost:8080.
OIDC_CONFIG_URL, OIDC_CLIENT_ID, OIDC_CLIENT_SECRET — enable interactive OIDC (all three required).
MCP_AUTH_AIRBYTE_CLOUD — set truthy to verify headless tokens against Airbyte Cloud's realm (fills JWKS URI / issuer / audience / algorithm with Airbyte Cloud defaults; each stays overridable).
MCP_AUTH_JWKS_URI / MCP_AUTH_JWT_PUBLIC_KEY — JWKS URL or static public key for verifying headless tokens.
MCP_AUTH_ISSUER / MCP_AUTH_AUDIENCE / MCP_AUTH_ALGORITHM — expected iss / aud claims and signing algorithm (recommended for headless).

If no transport auth variables are set, the HTTP server starts unauthenticated and logs a warning — acceptable only behind a trusted network boundary. The verifier assembly is provided by fastmcp-extensions.

Troubleshooting

Troubleshooting Local Connector Installation Issues

The MCP server uses PyAirbyte under the hood to manage Airbyte connectors. PyAirbyte supports both Python-native connectors (installed via pip/uv) and Docker-based connectors (run in containers).

To ensure docker connectors run correctly, please make sure which docker returns a valid path and that Docker Desktop (or an alternative container runtime) is running.

To ensure Python connectors run correctly, please make sure the Python version used to run the MCP server is compatible with the connector requirements. See the MCP server conifiguration section above for details on how to specify the Python version used by the MCP server.

Using Abolute Paths

Always use absolute paths in your environment files. Relative paths, tilde (~), or environment variables like $HOME will not work correctly, due to the way MCP servers are loaded and executed.

The AIRBYTE_PROJECT_DIR environment variable is critical - it specifies where PyAirbyte stores connector artifacts, cache files, and temporary data. Ensure this directory:

Uses an absolute path. (For example: /Users/username/airbyte-projects.)
Exists on the filesystem. (Use mkdir -p /path/to/dir to create it if needed.)
Is writable by the user account running the MCP server.

Note:

In rare cases, your agent may not be able to find uv or uvx if they are not in the system PATH or if the agent has a stale PATH value. In these cases, you can use which uvx from your own terminal to discover the full path to the uvx binary, and then provide the full path in your MCP configuration file.

Securing Your Secrets

The MCP server implements a security model that protects your credentials:

LLM sees only environment variable names - The AI assistant can see which variables are available (e.g., POSTGRES_PASSWORD) but never their actual values.
MCP server reads actual values - Only the MCP server process accesses the secret values when executing operations.
Credentials never exposed to LLM - Your API keys, passwords, and other secrets remain secure.

This design allows AI assistants to help configure connectors without compromising security.

Note: While the MCP server takes steps to secure your credentials, you are responsible for ensuring the agent is not given access to your secrets by other means. For example, Claude Code may have full local disk access when run in certain modes. Consult your agent's documentation for details on securing local files.

Contributing to the Airbyte MCP Server

PyAirbyte Contributing Guide

Additional resources

For issues and questions:

View Source

  1# Copyright (c) 2024 Airbyte, Inc., all rights reserved.
  2
  3r"""***Airbyte Replication MCP Server - Model Context Protocol Integration***
  4
  5> **NOTE:**
  6> This MCP server implementation is experimental and may change without notice between minor
  7> versions of PyAirbyte. The API may be modified or entirely refactored in future versions.
  8
  9The Airbyte Replication MCP (Model Context Protocol) server provides a standardized interface
 10for managing Airbyte connectors through MCP-compatible clients. This PyAirbyte-powered
 11experimental feature allows you to list connectors, validate configurations, and run sync
 12operations using the MCP protocol.
 13
 14## Getting Started with Airbyte Replication MCP
 15
 16To get started with the Airbyte Replication MCP server, follow these steps:
 17
 181. Create a Dotenv secrets file.
 192. Register the MCP server with your MCP client.
 203. Test the MCP server connection using your MCP client.
 21
 22### Step 1: Generate a Dotenv Secrets File
 23
 24To get started with the Airbyte Replication MCP server, you will need to create a dotenv
 25file containing your Airbyte Cloud credentials, as well as credentials for any
 26third-party services you wish to connect to via Airbyte.
 27
 28Create a file named `~/.mcp/airbyte_mcp.env` with the following content:
 29
 30```ini
 31# Airbyte Project Artifacts Directory
 32AIRBYTE_PROJECT_DIR=/path/to/any/writeable/project-dir
 33
 34# Airbyte Cloud Credentials (Required for Airbyte Cloud Operations)
 35AIRBYTE_CLOUD_CLIENT_ID=your_api_key
 36AIRBYTE_CLOUD_CLIENT_SECRET=your_api_secret
 37AIRBYTE_CLOUD_WORKSPACE_ID=your_workspace_id
 38
 39# API-Specific Credentials (Optional, depending on your connectors)
 40
 41# For example, for a PostgreSQL source connector:
 42# POSTGRES_HOST=your_postgres_host
 43# POSTGRES_PORT=5432
 44# POSTGRES_DB=your_database_name
 45# POSTGRES_USER=your_database_user
 46# POSTGRES_PASSWORD=your_database_password
 47
 48# For example, for a Stripe source connector:
 49# STRIPE_API_KEY=your_stripe_api_key
 50# STRIPE_API_SECRET=your_stripe_api_secret
 51# STRIPE_WEBHOOK_SECRET=your_stripe_webhook_secret
 52```
 53
 54Note:
 551. You can add more environment variables to this file as needed for different connectors. To start,
 56   you only need to create the file and pass it to the MCP server.
 572. Ensure that this file is kept secure, as it contains sensitive information. Your LLM
 58   *should never* be given direct access to this file or its contents.
 593. The MCP tools will give your LLM the ability to view *which* variables are available, but it
 60   does not give access to their values.
 614. The `AIRBYTE_PROJECT_DIR` variable specifies a directory where the MCP server can
 62   store temporary project files. Ensure this directory is writable by the user running
 63   the MCP server.
 64
 65### Step 2: Registering the MCP Server
 66
 67First install `uv` (`brew install uv`).
 68
 69Then, create a file named `server_config.json` (or the file name required by your MCP client)
 70with the following content. This uses `uvx` (from `brew install uv`) to run the MCP
 71server. If a matching version Python is not yet installed, a `uv`-managed Python
 72version will be installed automatically. This will also auto-update to use the
 73"latest" Airbyte MCP release at time of launch. You can alternatively pin to a
 74specific version of Python and/or of the Airbyte library if you have special
 75requirements.
 76
 77```json
 78{
 79  "mcpServers": {
 80    "airbyte": {
 81      "command": "uvx",
 82      "args": [
 83        "--python=3.11",
 84        "--from=airbyte@latest",
 85        "airbyte-mcp"
 86      ],
 87      "env": {
 88        "AIRBYTE_MCP_ENV_FILE": "/path/to/my/.mcp/airbyte_mcp.env",
 89        "AIRBYTE_CLOUD_MCP_SAFE_MODE": "1",
 90        "AIRBYTE_CLOUD_MCP_READONLY_MODE": "0"
 91      }
 92    }
 93  }
 94}
 95```
 96
 97Note:
 98- Replace `/path/to/my/.mcp/airbyte_mcp.env` with the absolute path to your dotenv file created in
 99  Step 1.
100
101### Step 3: Testing the MCP Server Connection
102
103You can test the MCP server connection using your MCP client.
104
105Helpful prompts to try:
106
1071. "Use your MCP tools to list all available Airbyte connectors."
1082. "Use your MCP tools to get information about the Airbyte Stripe connector."
1093. "Use your MCP tools to list all variables you have access to in the dotenv secrets
110   file."
1114. "Use your MCP tools to check your connection to your Airbyte Cloud workspace."
1125. "Use your MCP tools to list all available destinations in my Airbyte Cloud workspace."
113
114## Airbyte Cloud MCP Server Safety
115
116The Airbyte Replication MCP server supports environment variables to control safety and access
117levels for Airbyte Cloud operations.
118
119**Important:** The below settings only affect Cloud operations; local operations are not affected.
120
121### Airbyte Cloud Safe Mode
122
123Safe mode is enabled by default and is controlled by the `AIRBYTE_CLOUD_MCP_SAFE_MODE` environment
124variable.
125
126When enabled, write operations are allowed but destructive operations (updates, deletions) are
127only allowed for objects created within the same session. For example, you can create a new
128connector and then delete it, but you cannot delete an existing connector that was not created in
129the current session. Modifications to configurations are likewise treated as potentially destructive
130and are only allowed for objects created in the current session.
131
132Set the environment variable `AIRBYTE_CLOUD_MCP_SAFE_MODE=0` to disable safe mode.
133
134### Airbyte Cloud Read-Only Mode
135
136Read-only mode is not enabled by default and is controlled by the
137`AIRBYTE_CLOUD_MCP_READONLY_MODE` environment variable.
138
139When enabled, only read-only Cloud tools are available. Write and destructive operations are
140disabled.
141
142This mode does allow running syncs on existing connectors, since sync operations
143are not considered to be modifications of the Airbyte Cloud workspace.
144
145Set the environment variable `AIRBYTE_CLOUD_MCP_READONLY_MODE=1` to enable read-only mode.
146
147## Authentication for Remote (HTTP) Servers
148
149The steps above run the MCP server over **stdio** — the client launches the
150server process locally, so there is no transport-layer auth and the only
151credentials that matter are your Airbyte Cloud creds in the dotenv file.
152
153When the server is instead exposed over **HTTP** (`airbyte-mcp-http` /
154`poe mcp-serve-http`), it verifies an `Authorization: Bearer <token>` on every
155request. Two client shapes are supported on the same deployment (combined
156automatically when both are configured):
157
158### Humans → interactive OIDC
159
160Set `OIDC_CONFIG_URL`, `OIDC_CLIENT_ID`, and `OIDC_CLIENT_SECRET`. Interactive
161clients open a browser (Keycloak Authorization Code + PKCE) and the resulting
162token is verified by the server. No bearer token to manage by hand.
163
164### Machines / agents → headless bearer token
165
166There is **no** transport mode that accepts a raw `client_id` + `client_secret`
167in a header. A headless agent **mints its own short-lived bearer token** and
168sends it as `Authorization: Bearer <token>`; the server verifies the signature
169(no browser, no stored/rotating refresh token).
170
171For Airbyte Cloud, set `MCP_AUTH_AIRBYTE_CLOUD=true` on the server so it verifies
172tokens against Airbyte Cloud's application-client realm without hand-configuring
173URLs. The agent mints an Airbyte Cloud access token from its
174`AIRBYTE_CLOUD_CLIENT_ID` / `AIRBYTE_CLOUD_CLIENT_SECRET` (the
175`https://api.airbyte.com/v1/applications/token` endpoint) and sends it as the
176bearer. That single token both authenticates transport (verified by the server)
177and authorizes downstream Cloud API calls, because an Airbyte-Cloud-issued token
178is itself a valid Cloud API bearer. Tokens are short-lived (~15 min), so
179re-mint on expiry / on a `401` rather than pinning a static token.
180
181Clients that support HTTP transports can pass the token via a `headers` block in
182their MCP config:
183
184```json
185{
186  "mcpServers": {
187    "airbyte": {
188      "url": "https://<host>/mcp",
189      "headers": {
190        "Authorization": "Bearer ${AIRBYTE_MCP_TOKEN}"
191      }
192    }
193  }
194}
195```
196
197### Server environment variables (HTTP mode)
198
199- `MCP_SERVER_URL` — public base URL of the server (also used for OIDC redirect
200  callbacks); defaults to `http://localhost:8080`.
201- `OIDC_CONFIG_URL`, `OIDC_CLIENT_ID`, `OIDC_CLIENT_SECRET` — enable interactive
202  OIDC (all three required).
203- `MCP_AUTH_AIRBYTE_CLOUD` — set truthy to verify headless tokens against Airbyte
204  Cloud's realm (fills JWKS URI / issuer / audience / algorithm with Airbyte
205  Cloud defaults; each stays overridable).
206- `MCP_AUTH_JWKS_URI` / `MCP_AUTH_JWT_PUBLIC_KEY` — JWKS URL or static public key
207  for verifying headless tokens.
208- `MCP_AUTH_ISSUER` / `MCP_AUTH_AUDIENCE` / `MCP_AUTH_ALGORITHM` — expected `iss`
209  / `aud` claims and signing algorithm (recommended for headless).
210
211If no transport auth variables are set, the HTTP server starts
212**unauthenticated** and logs a warning — acceptable only behind a trusted
213network boundary. The verifier assembly is provided by
214[`fastmcp-extensions`](https://github.com/airbytehq/fastmcp-extensions).
215
216## Troubleshooting
217
218### Troubleshooting Local Connector Installation Issues
219
220The MCP server uses PyAirbyte under the hood to manage Airbyte connectors. PyAirbyte
221supports both Python-native connectors (installed via pip/uv) and Docker-based connectors
222(run in containers).
223
224To ensure docker connectors run correctly, please make sure `which docker` returns a valid
225path and that Docker Desktop (or an alternative container runtime) is running.
226
227To ensure Python connectors run correctly, please make sure the Python version used to run the
228MCP server is compatible with the connector requirements. See the MCP server conifiguration
229section above for details on how to specify the Python version used by the MCP server.
230
231### Using Abolute Paths
232
233**Always use absolute paths in your environment files.** Relative paths, tilde (`~`), or
234environment variables like `$HOME` will not work correctly, due to the way MCP servers
235are loaded and executed.
236
237The `AIRBYTE_PROJECT_DIR` environment variable is critical - it specifies where PyAirbyte
238stores connector artifacts, cache files, and temporary data. Ensure this directory:
239
240- Uses an absolute path. (For example: `/Users/username/airbyte-projects`.)
241- Exists on the filesystem. (Use `mkdir -p /path/to/dir` to create it if needed.)
242- Is writable by the user account running the MCP server.
243
244Note:
245- In rare cases, your agent may not be able to find `uv` or `uvx` if they are not in the system
246  `PATH` or if the agent has a stale `PATH` value. In these cases, you can use `which uvx` from
247  your own terminal to discover the full path to the `uvx` binary, and then provide the full path
248  in your MCP configuration file.
249
250### Securing Your Secrets
251
252The MCP server implements a security model that protects your credentials:
253
254- **LLM sees only environment variable names** - The AI assistant can see which variables
255  are available (e.g., `POSTGRES_PASSWORD`) but never their actual values.
256- **MCP server reads actual values** - Only the MCP server process accesses the secret
257  values when executing operations.
258- **Credentials never exposed to LLM** - Your API keys, passwords, and other secrets remain secure.
259
260This design allows AI assistants to help configure connectors without compromising security.
261
262Note: While the MCP server takes steps to secure your credentials, you are responsible for
263ensuring the agent is not given access to your secrets by other means. For example, Claude Code
264may have *full* local disk access when run in certain modes. Consult your agent's documentation
265for details on securing local files.
266
267## Contributing to the Airbyte MCP Server
268
269- [PyAirbyte Contributing Guide](https://github.com/airbytehq/PyAirbyte/blob/main/docs/CONTRIBUTING.md)
270
271### Additional resources
272
273- [Airbyte AI Agents Documentation Home](https://docs.airbyte.com/ai-agents/)
274- [MCP Documentation Home](https://modelcontextprotocol.io/)
275
276For issues and questions:
277- [PyAirbyte GitHub Issues](https://github.com/airbytehq/pyairbyte/issues)
278- [PyAirbyte Discussions](https://github.com/airbytehq/pyairbyte/discussions)
279
280"""  # noqa: D415
281
282from airbyte.mcp import cloud, local, registry, server
283
284
285__all__: list[str] = [
286    "cloud",
287    "local",
288    "registry",
289    "server",
290]
291
292__docformat__ = "google"