# Module airbyte.mcp

Copy Page

***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[​](#getting-started-with-airbyte-replication-mcp "Direct link to Getting Started with Airbyte Replication MCP")

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

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

### Step 1: Generate a Dotenv Secrets File[​](#step-1-generate-a-dotenv-secrets-file "Direct link to 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:

1. 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.
2. 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.
3. The MCP tools will give your LLM the ability to view *which* variables are available, but it does not give access to their values.
4. 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[​](#step-2-registering-the-mcp-server "Direct link to 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[​](#step-3-testing-the-mcp-server-connection "Direct link to Step 3: Testing the MCP Server Connection")

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

Helpful prompts to try:

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

## Airbyte Cloud MCP Server Safety[​](#airbyte-cloud-mcp-server-safety "Direct link to 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[​](#airbyte-cloud-safe-mode "Direct link to 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[​](#airbyte-cloud-read-only-mode "Direct link to 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.

## Troubleshooting[​](#troubleshooting "Direct link to Troubleshooting")

### Troubleshooting Local Connector Installation Issues[​](#troubleshooting-local-connector-installation-issues "Direct link to 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[​](#using-abolute-paths "Direct link to 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[​](#securing-your-secrets "Direct link to 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[​](#contributing-to-the-airbyte-mcp-server "Direct link to Contributing to the Airbyte MCP Server")

* [PyAirbyte Contributing Guide](https://github.com/airbytehq/PyAirbyte/blob/main/docs/CONTRIBUTING.md)

### Additional resources[​](#additional-resources "Direct link to Additional resources")

* [Airbyte AI Agents Documentation Home](https://docs.airbyte.com/ai-agents/)
* [MCP Documentation Home](https://modelcontextprotocol.io/)

For issues and questions:

* [PyAirbyte GitHub Issues](https://github.com/airbytehq/pyairbyte/issues)
* [PyAirbyte Discussions](https://github.com/airbytehq/pyairbyte/discussions)

## Sub-modules[​](#sub-modules "Direct link to Sub-modules")

* airbyte.mcp.cloud
* airbyte.mcp.local
* airbyte.mcp.prompts
* airbyte.mcp.registry
* airbyte.mcp.server