airbyte.mcp

  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## Troubleshooting
148
149### Troubleshooting Local Connector Installation Issues
150
151The MCP server uses PyAirbyte under the hood to manage Airbyte connectors. PyAirbyte
152supports both Python-native connectors (installed via pip/uv) and Docker-based connectors
153(run in containers).
154
155To ensure docker connectors run correctly, please make sure `which docker` returns a valid
156path and that Docker Desktop (or an alternative container runtime) is running.
157
158To ensure Python connectors run correctly, please make sure the Python version used to run the
159MCP server is compatible with the connector requirements. See the MCP server conifiguration
160section above for details on how to specify the Python version used by the MCP server.
161
162### Using Abolute Paths
163
164**Always use absolute paths in your environment files.** Relative paths, tilde (`~`), or
165environment variables like `$HOME` will not work correctly, due to the way MCP servers
166are loaded and executed.
167
168The `AIRBYTE_PROJECT_DIR` environment variable is critical - it specifies where PyAirbyte
169stores connector artifacts, cache files, and temporary data. Ensure this directory:
170
171- Uses an absolute path. (For example: `/Users/username/airbyte-projects`.)
172- Exists on the filesystem. (Use `mkdir -p /path/to/dir` to create it if needed.)
173- Is writable by the user account running the MCP server.
174
175Note:
176- In rare cases, your agent may not be able to find `uv` or `uvx` if they are not in the system
177  `PATH` or if the agent has a stale `PATH` value. In these cases, you can use `which uvx` from
178  your own terminal to discover the full path to the `uvx` binary, and then provide the full path
179  in your MCP configuration file.
180
181### Securing Your Secrets
182
183The MCP server implements a security model that protects your credentials:
184
185- **LLM sees only environment variable names** - The AI assistant can see which variables
186  are available (e.g., `POSTGRES_PASSWORD`) but never their actual values.
187- **MCP server reads actual values** - Only the MCP server process accesses the secret
188  values when executing operations.
189- **Credentials never exposed to LLM** - Your API keys, passwords, and other secrets remain secure.
190
191This design allows AI assistants to help configure connectors without compromising security.
192
193Note: While the MCP server takes steps to secure your credentials, you are responsible for
194ensuring the agent is not given access to your secrets by other means. For example, Claude Code
195may have *full* local disk access when run in certain modes. Consult your agent's documentation
196for details on securing local files.
197
198## Contributing to the Airbyte MCP Server
199
200- [PyAirbyte Contributing Guide](https://github.com/airbytehq/PyAirbyte/blob/main/docs/CONTRIBUTING.md)
201
202### Additional resources
203
204- [Airbyte AI Agents Documentation Home](https://docs.airbyte.com/ai-agents/)
205- [MCP Documentation Home](https://modelcontextprotocol.io/)
206
207For issues and questions:
208- [PyAirbyte GitHub Issues](https://github.com/airbytehq/pyairbyte/issues)
209- [PyAirbyte Discussions](https://github.com/airbytehq/pyairbyte/discussions)
210
211"""  # noqa: D415
212
213from airbyte.mcp import cloud_ops, connector_registry, local_ops, server
214
215
216__all__: list[str] = [
217    "cloud_ops",
218    "connector_registry",
219    "local_ops",
220    "server",
221]
222
223__docformat__ = "google"