airbyte.mcp.server

  1# Copyright (c) 2024 Airbyte, Inc., all rights reserved.
  2"""Experimental MCP (Model Context Protocol) server for PyAirbyte connector management."""
  3
  4from __future__ import annotations
  5
  6import asyncio
  7import sys
  8
  9from fastmcp_extensions import mcp_server
 10
 11from airbyte._util.meta import set_mcp_mode
 12from airbyte.mcp._config import load_secrets_to_env_vars
 13from airbyte.mcp._tool_utils import (
 14    AIRBYTE_EXCLUDE_MODULES_CONFIG_ARG,
 15    AIRBYTE_INCLUDE_MODULES_CONFIG_ARG,
 16    AIRBYTE_READONLY_MODE_CONFIG_ARG,
 17    API_URL_CONFIG_ARG,
 18    BEARER_TOKEN_CONFIG_ARG,
 19    CLIENT_ID_CONFIG_ARG,
 20    CLIENT_SECRET_CONFIG_ARG,
 21    CONFIG_API_URL_CONFIG_ARG,
 22    WORKSPACE_ID_CONFIG_ARG,
 23    airbyte_module_filter,
 24    airbyte_readonly_mode_filter,
 25)
 26from airbyte.mcp.cloud import register_cloud_tools
 27from airbyte.mcp.local import register_local_tools
 28from airbyte.mcp.prompts import register_prompts
 29from airbyte.mcp.registry import register_registry_tools
 30
 31
 32# =============================================================================
 33# Server Instructions
 34# =============================================================================
 35# This text is provided to AI agents via the MCP protocol's "instructions" field.
 36# It helps agents understand when to use this server's tools, especially when
 37# tool search is enabled. For more context, see:
 38# - FastMCP docs: https://gofastmcp.com/servers/overview
 39# - Claude tool search: https://www.anthropic.com/news/tool-use-improvements
 40# =============================================================================
 41
 42MCP_SERVER_INSTRUCTIONS = """
 43PyAirbyte connector management and data integration server for discovering,
 44deploying, and running Airbyte connectors.
 45
 46Use this server for:
 47- Discovering connectors from the Airbyte registry (sources and destinations)
 48- Deploying sources, destinations, and connections to Airbyte Cloud
 49- Running cloud syncs and monitoring sync status
 50- Managing custom connector definitions in Airbyte Cloud
 51- Local connector execution for data extraction without cloud deployment
 52- Listing and describing environment variables for connector configuration
 53
 54Operational modes:
 55- Cloud operations: Deploy and manage connectors on Airbyte Cloud (requires
 56  AIRBYTE_CLOUD_CLIENT_ID, AIRBYTE_CLOUD_CLIENT_SECRET, AIRBYTE_CLOUD_WORKSPACE_ID)
 57- Local operations: Run connectors locally for data extraction (requires
 58  AIRBYTE_PROJECT_DIR for artifact storage)
 59
 60Safety features:
 61- Safe mode (default): Restricts destructive operations to objects created in
 62  the current session
 63- Read-only mode: Disables all write operations for cloud resources
 64""".strip()
 65
 66set_mcp_mode()
 67load_secrets_to_env_vars()
 68
 69app = mcp_server(
 70    name="airbyte-mcp",
 71    package_name="airbyte",
 72    instructions=MCP_SERVER_INSTRUCTIONS,
 73    include_standard_tool_filters=True,
 74    server_config_args=[
 75        AIRBYTE_READONLY_MODE_CONFIG_ARG,
 76        AIRBYTE_EXCLUDE_MODULES_CONFIG_ARG,
 77        AIRBYTE_INCLUDE_MODULES_CONFIG_ARG,
 78        WORKSPACE_ID_CONFIG_ARG,
 79        BEARER_TOKEN_CONFIG_ARG,
 80        CLIENT_ID_CONFIG_ARG,
 81        CLIENT_SECRET_CONFIG_ARG,
 82        API_URL_CONFIG_ARG,
 83        CONFIG_API_URL_CONFIG_ARG,
 84    ],
 85    tool_filters=[
 86        airbyte_readonly_mode_filter,
 87        airbyte_module_filter,
 88    ],
 89)
 90"""The Airbyte MCP Server application instance."""
 91
 92# Register tools from each module
 93register_cloud_tools(app)
 94register_local_tools(app)
 95register_registry_tools(app)
 96register_prompts(app)
 97
 98
 99def main() -> None:
100    """@private Main entry point for the MCP server.
101
102    This function starts the FastMCP server to handle MCP requests.
103
104    It should not be called directly; instead, consult the MCP client documentation
105    for instructions on how to connect to the server.
106    """
107    print("Starting Airbyte MCP server.", file=sys.stderr)
108    try:
109        asyncio.run(app.run_stdio_async())
110    except KeyboardInterrupt:
111        print("Airbyte MCP server interrupted by user.", file=sys.stderr)
112    except Exception as ex:
113        print(f"Error running Airbyte MCP server: {ex}", file=sys.stderr)
114        sys.exit(1)
115
116    print("Airbyte MCP server stopped.", file=sys.stderr)
117
118
119if __name__ == "__main__":
120    main()