airbyte.mcp
PyAirbyte 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 PyAirbyte MCP (Model Context Protocol) server provides a standardized interface for managing Airbyte connectors through MCP-compatible clients. This experimental feature allows you to list connectors, validate configurations, and run sync operations using the MCP protocol.
Getting Started with PyAirbyte MCP
To get started with the PyAirbyte 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 PyAirbyte 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_DIRvariable 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.envwith 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 PyAirbyte 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.
Contributing to the Airbyte MCP Server
Additional resources
For issues and questions:
1# Copyright (c) 2024 Airbyte, Inc., all rights reserved. 2 3r"""***PyAirbyte 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 PyAirbyte MCP (Model Context Protocol) server provides a standardized interface for 10managing Airbyte connectors through MCP-compatible clients. This experimental feature 11allows you to list connectors, validate configurations, and run sync operations using 12the MCP protocol. 13 14## Getting Started with PyAirbyte MCP 15 16To get started with the PyAirbyte 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 PyAirbyte 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 PyAirbyte MCP server supports environment variables to control safety and access levels for 117Airbyte 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## Contributing to the Airbyte MCP Server 148 149- [PyAirbyte Contributing Guide](https://github.com/airbytehq/PyAirbyte/blob/main/docs/CONTRIBUTING.md) 150 151### Additional resources 152 153- [Model Context Protocol Documentation](https://modelcontextprotocol.io/) 154- [MCP Python SDK](https://github.com/modelcontextprotocol/python-sdk) 155 156For issues and questions: 157- [PyAirbyte GitHub Issues](https://github.com/airbytehq/pyairbyte/issues) 158- [PyAirbyte Discussions](https://github.com/airbytehq/pyairbyte/discussions) 159 160""" # noqa: D415 161 162from airbyte.mcp import cloud_ops, connector_registry, local_ops, server 163 164 165__all__: list[str] = [ 166 "cloud_ops", 167 "connector_registry", 168 "local_ops", 169 "server", 170] 171 172__docformat__ = "google"