マーケティングオートメーションMCPサーバー

marketing-automation-mcpは、決定論的なキャンペーンレポート作成、プロバイダーによる予算最適化、コピー生成、およびデモ用オーディエンスセグメンテーションのためのPython製MCPサーバーです。

本リポジトリでは、アドホックなセットアップよりも再現性を優先しています：

• サポート対象Python: 3.12 および 3.13

• ローカルブートストラップ: uv

• 主要なMCPトランスポート: stdio

• ローカルのPython 3.14.x は互換性作業として扱われ、サポート対象のベースラインではありません

現在のスコープ

本リポジトリの公開MCPコントラクトは、意図的に範囲を絞っています：

• generate_campaign_report

• optimize_campaign_budget

• create_campaign_copy

• analyze_audience_segments

現在、サポートされているサーバーインターフェースの一部であるツールはこれら4つのみです。src/tools/配下のその他のモジュールは、内部用または将来的なコードパスとして存在しており、本番環境のMCP機能として扱うべきではありません。

Related MCP server: Google Ads MCP Server

実行モード

• DEMO_MODE=true デモおよびコントラクトテスト用に、決定論的なサンプルデータを返します。

• DEMO_MODE=false 実際のプラットフォーム認証情報と選択されたAIプロバイダーを使用します。 ライブ環境の依存関係が欠落している場合は、偽の出力ではなく、構造化されたblockedレスポンスを返します。

クリーンなマシンセットアップ

uv sync --python 3.13 --extra dev
cp .env.example .env
uv run python -m compileall src tests dashboard
uv run pytest

pipによるフォールバックが必要な場合：

python3.13 -m venv .venv
source .venv/bin/activate
python -m pip install --upgrade pip
python -m pip install -e ".[dev]"

サーバーの実行

サポートされているトランスポートモードでMCPサーバーを起動します：

uv run python -m src.server

現在、サーバーはstdioトランスポートのみを文書化およびサポートしています。

Claude Desktopの設定：

{
  "mcpServers": {
    "marketing-automation": {
      "command": "uv",
      "args": ["run", "python", "-m", "src.server"],
      "cwd": "/absolute/path/to/Marketing-Automation-MCP-Server"
    }
  }
}

設定

cp .env.example .env

最低限必要な設定：

• デモモードのみ：

  • DEMO_MODE=true

• ライブレポートおよび最適化：

  • DEMO_MODE=false

  • 1つ以上のプラットフォーム認証情報セット

• ライブコピー生成：

  • DEMO_MODE=false

  • AI_PROVIDER=openai

  • OPENAI_API_KEY=...

  • AI_OPENAI_MODEL=gpt-5.4

オプションのプロバイダー環境変数：

• ANTHROPIC_API_KEY, ANTHROPIC_MODEL

• GEMINI_API_KEY, GEMINI_MODEL

安定したライブ動作のために、以下を設定してください：

• SECRET_KEY

• ENCRYPTION_KEY

ENCRYPTION_KEYが欠落している場合、そのプロセスではAPIキーの暗号化が無効になり、サーバーは警告をログに出力します。

ツールコントラクト

すべてのツールレスポンスには、以下のトップレベルフィールドが含まれます：

{
  "status": "ok | blocked",
  "mode": "demo | live",
  "blocked_reason": "optional string",
  "warnings": []
}

完全なコントラクトについては、docs/api/README.mdを参照してください。

内部書き込みの副作用

ライブレポートおよび最適化フローでは、設定されたデータベースに内部監査記録が永続化される場合があります：

• レポートフローは、正規化されたキャンペーンスナップショットを永続化できます

• 最適化フローは、AIの意思決定履歴を永続化できます

これらの書き込みは、可観測性とリプレイの安全性を確保するための内部的な副作用です。これらは公開MCPレスポンスコントラクトの一部ではありません。

検証コマンド

uv run python -m compileall src tests dashboard
uv run pytest
uv run python -c "import src.server, src.cli, src.ai_engine, src.performance; print('imports ok')"
docker build -t marketing-automation-mcp:latest .

ドキュメント

• クイックスタート

• APIリファレンス

• ワークフロー例

• デモガイド

• オペレーターランブック

• システム監査レビュー資料