Marketing Automation

marketing-automation-mcp is a Python MCP server for deterministic campaign reporting, provider-backed budget optimization, copy generation, and demo-only audience segmentation.

This repo now favors reproducibility over ad hoc setup:

• Supported Python: 3.12 and 3.13
• Local bootstrap: uv
• Primary MCP transport: stdio
• Local Python 3.14.x is treated as compatibility work, not the supported baseline

Current Scope

The public MCP contract in this repo is intentionally narrow:

• generate_campaign_report
• optimize_campaign_budget
• create_campaign_copy
• analyze_audience_segments

Only these four tools are part of the supported server surface today. Other modules under src/tools/ exist as internal or aspirational code paths and should not be treated as production MCP features.

Execution Modes

• DEMO_MODE=true Returns deterministic sample data for demos and contract testing.
• DEMO_MODE=false Uses real platform credentials and the selected AI provider. Missing live dependencies return structured blocked responses instead of fabricated output.

Clean Machine Setup

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

If you need a pip fallback:

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

Run The Server

Start the MCP server in its supported transport mode:

uv run python -m src.server

The server currently documents and supports stdio transport only.

Claude Desktop configuration:

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

Configure

cp .env.example .env

Minimum useful configurations:

• Demo mode only:
  • DEMO_MODE=true
• Live reporting and optimization:
  • DEMO_MODE=false
  • one or more platform credential sets
• Live copy generation:
  • DEMO_MODE=false
  • AI_PROVIDER=openai
  • OPENAI_API_KEY=...
  • AI_OPENAI_MODEL=gpt-5.4

Optional provider env vars:

• ANTHROPIC_API_KEY, ANTHROPIC_MODEL
• GEMINI_API_KEY, GEMINI_MODEL

For stable live behavior, set:

• SECRET_KEY
• ENCRYPTION_KEY

If ENCRYPTION_KEY is missing, API-key encryption is disabled for that process and the server logs a warning.

Tool Contract

Every tool response includes these top-level fields:

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

See the full contract in docs/api/README.md.

Internal Write Side Effects

Live report and optimization flows may persist internal audit records to the configured database:

• report flows can persist normalized campaign snapshots
• optimization flows can persist AI decision history

These writes are internal side effects for observability and replay safety. They are not part of the public MCP response contract.

Validation Commands

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 .

Documentation

• Quick start
• API reference
• Example workflows
• Demo guide
• Operator runbook
• System audit review docs