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