1# Copyright (c) 2024 Airbyte, Inc., all rights reserved.
  2
  3r"""***PyAirbyte MCP Server - Model Context Protocol Integration***
  4
  5The PyAirbyte MCP (Model Context Protocol) server provides a standardized interface for
  6managing Airbyte connectors through MCP-compatible clients. This experimental feature
  7allows you to list connectors, validate configurations, and run sync operations using
  8the MCP protocol.
  9
 10The Model Context Protocol (MCP) is an open standard that enables AI assistants and
 11other tools to securely connect to data sources, tools, and services. PyAirbyte's MCP
 12server implementation allows you to build and interact with Airbyte connectors through
 13this standardized protocol.
 14
 15Create a JSON configuration file to register the PyAirbyte MCP server with your MCP
 16client. Create a file named `server_config.json`:
 17
 18> **NOTE:**
 19> This MCP server implementation is experimental and may change without notice between minor
 20> versions of PyAirbyte. The API may be modified or entirely refactored in future versions.
 21
 22# MCP Server Configuration
 23
 24Assuming `uv` is installed, you can use the following configuration:
 25
 26```json
 27{
 28  "mcpServers": {
 29    "airbyte": {
 30      "command": "uvx",
 31      "args": ["--from=airbyte", "airbyte-mcp"],
 32      "env": {
 33        "AIRBYTE_MCP_ENV_FILE": "~/.mcp/airbyte_mcp.env"
 34      }
 35    }
 36  }
 37}
 38```
 39
 40If you prefer to pre-install, first run `uv install airbyte` or `pipx install airbyte`,
 41and then create the configuration file as follows:
 42
 43```json
 44{
 45  "mcpServers": {
 46    "airbyte": {
 47      "command": "airbyte-mcp",
 48      "args": [],
 49      "env": {
 50        "AIRBYTE_MCP_ENV_FILE": "~/.mcp/airbyte_mcp.env"
 51      }
 52    }
 53  }
 54}
 55```
 56
 57## Testing the MCP Server
 58
 59You can use your tool of choice to test the MCP server. Below we'll use the Devin `mcp-cli`
 60tool. First, we install our MCP CLI client:
 61
 62```
 63uv tool install devin-mcp-cli
 64```
 65
 66Next, we export the configuration path so that MCP CLI can find your server:
 67
 68```bash
 69# You can use a custom path in your home directory:
 70export MCP_CLI_CONFIG_PATH=~/.mcp/mcp_server_config.json
 71touch $MCP_CLI_CONFIG_PATH
 72
 73# Then you can symlink your file to also be available in Claude Desktop path:
 74mkdir -p ~/Library/"Application Support"/Claude
 75ln -s $MCP_CLI_CONFIG_PATH ~/Library/"Application Support"/Claude/claude_desktop_config.json
 76
 77# Confirm the Claude Desktop symlink is working:
 78cat ~/Library/"Application Support"/Claude/claude_desktop_config.json
 79```
 80
 81### Check that your server is properly registered
 82
 83```bash
 84mcp-cli server list
 85mcp-cli tool list
 86```
 87
 88This should show `airbyte` in the list of available servers.
 89
 90### Verify the server can be reached
 91
 92```bash
 93mcp-cli server check
 94```
 95
 96This should show `✓ Connected` for the Airbyte server with a list of available tools.
 97
 98### Test the MCP Tools
 99
100You should now be able to validate specific tools:
101
102```bash
103# Show a list of all available Airbyte source connectors:
104mcp-cli tool call list_connectors --server airbyte
105
106# Get JSON schema of expected config for the specified connector:
107mcp-cli tool call get_config_spec --server airbyte --input '{"connector_name": "source-pokeapi"}'
108
109# Validate the provided configuration:
110mcp-cli tool call validate_config --server airbyte --input '{
111  "connector_name": "source-pokeapi",
112  "config": {
113    "pokemon_name": "pikachu"
114  }
115}'
116
117# Run a sync operation with the provided configuration:
118mcp-cli tool call run_sync --server airbyte --input '{
119  "connector_name": "source-pokeapi",
120  "config": {
121    "pokemon_name": "pikachu"
122  }
123}'
124```
125
126## Contributing to PyAirbyte and the Airbyte MCP Server
127
128The Airbyte MCP server is part of the PyAirbyte project. Contributions are welcome!
129
130You can contribute to the MCP server by adding new tools, improving existing functionality, or
131fixing bugs. The server is built using the FastMCP framework, which provides a flexible
132interface for defining tools and handling requests.
133
134As a starting point, you can clone the repo and inspect the server definition using the `fastmcp`
135CLI tool:
136
137```bash
138poetry install --all-extras
139poetry run fastmcp inspect airbyte/mcp/server.py:app
140```
141
142In your MCP config, you can test your development updates using `poetry` as the entrypoint:
143
144```json
145{
146  "mcpServers": {
147    "airbyte": {
148      "command": "poetry",
149      "args": [
150        "--directory=~/repos/PyAirbyte",
151        "run",
152        "airbyte-mcp"
153      ],
154      "env": {
155        "AIRBYTE_MCP_ENV_FILE": "~/.mcp/airbyte_mcp.env"
156      }
157    }
158  }
159}
160```
161
162### Additional resources
163
164- [Model Context Protocol Documentation](https://modelcontextprotocol.io/)
165- [MCP Python SDK](https://github.com/modelcontextprotocol/python-sdk)
166
167For issues and questions:
168- [PyAirbyte Contributing Guide](https://github.com/airbytehq/PyAirbyte/blob/main/docs/CONTRIBUTING.md)
169- [PyAirbyte GitHub Issues](https://github.com/airbytehq/pyairbyte/issues)
170- [PyAirbyte Discussions](https://github.com/airbytehq/pyairbyte/discussions)
171
172"""  # noqa: D415
173
174from airbyte.mcp import server
175
176
177__all__: list[str] = ["server"]
178
179__docformat__ = "google"