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## 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"