MCP Write Server
A NON-OFFICIAL write-enabled extension of the official Braze MCP server, designed for Solution Engineers to create demos, trigger campaigns, and manage test environments.
⚠️ Important Safety Notice
This server enables WRITE OPERATIONS to your Braze workspace. It includes multiple safety mechanisms:
- Workspace validation: Only works with demo/POC/test workspaces by default
- Rate limiting: Prevents accidental spam
- Dry run mode: Test operations without making changes
- Confirmation requirements: Destructive operations need explicit confirmation
- Production blocking: Prevents writes to production workspaces unless explicitly enabled
Features
Write Operations
- ✅ User profile management (attributes, events, purchases)
- ✅ Campaign triggering and management
- ✅ Canvas triggering and management
- ✅ Catalog item management
- ✅ Content block management
- ✅ User deletion and identification
Safety Features
- ✅ Environment-based workspace validation
- ✅ Rate limiting per operation type
- ✅ Dry run mode for all operations
- ✅ Confirmation requirements for destructive operations
- ✅ Comprehensive logging and audit trail
Installation
pip install -e .
Or with uv:
uv pip install -e .
Configuration
Environment Variables
# Required
BRAZE_API_KEY=your-api-key-here
BRAZE_BASE_URL=https://rest.iad-01.braze.com
# Safety Configuration
BRAZE_WRITE_ENABLED=true # Enable write operations
BRAZE_ALLOW_PRODUCTION=false # Block production workspaces
BRAZE_ALLOWED_WORKSPACES=demo-,poc-,test- # Allowed workspace patterns
BRAZE_DRY_RUN_DEFAULT=false # Default dry run mode
# Rate Limits
BRAZE_MAX_SENDS_PER_HOUR=1000 # Max campaign/canvas sends per hour
BRAZE_MAX_CATALOG_UPDATES_PER_MIN=100 # Max catalog updates per minute
MCP Client Configuration
Add to your MCP client configuration (e.g., Claude Desktop):
{
"mcpServers": {
"braze-write": {
"command": "python",
"args": ["-m", "braze_mcp_write.main"],
"env": {
"BRAZE_API_KEY": "your-api-key",
"BRAZE_BASE_URL": "https://rest.iad-01.braze.com",
"BRAZE_WRITE_ENABLED": "true",
"BRAZE_ALLOWED_WORKSPACES": "demo-,poc-,test-"
}
}
}
}
Usage Examples
Update User Attributes
await update_user_attributes(
ctx,
external_id="user_12345",
attributes={
"first_name": "John",
"last_name": "Doe",
"email": "[email protected]",
"subscription_tier": "premium"
}
)
Track Custom Event
await track_event(
ctx,
event_name="completed_tutorial",
external_id="user_12345",
properties={
"tutorial_name": "Getting Started",
"completion_time_seconds": 180
}
)
Send Campaign
await send_campaign(
ctx,
campaign_id="your-campaign-id",
recipients=[{
"external_user_id": "user_12345"
}]
)
Trigger Canvas
await trigger_canvas(
ctx,
canvas_id="your-canvas-id",
recipients=[{
"external_user_id": "user_12345"
}],
canvas_entry_properties={
"promo_code": "DEMO2024"
}
)
Dry Run Mode
Test any operation without making changes:
result = await update_user_attributes(
ctx,
external_id="user_12345",
attributes={"test_field": "test_value"},
dry_run=True # No actual API call made
)
Architecture
braze_mcp_write/
├── models/ # Pydantic models for validation
│ ├── errors.py
│ └── responses.py
├── tools/ # MCP tool implementations
│ ├── users_write.py # User tracking operations
│ ├── campaigns_write.py
│ ├── canvas_write.py
│ ├── catalogs_write.py
│ └── content_blocks_write.py
├── utils/ # Utilities
│ ├── context.py # Context management
│ ├── http.py # HTTP client
│ ├── logging.py # Logging setup
│ └── safety.py # Safety mechanisms
├── registry_builder.py # Auto-discovery system
├── server.py # FastMCP server
└── main.py # Entry point
Development
Running Tests
pytest
Code Formatting
black .
ruff check .
Safety Best Practices
- Always use demo workspaces: Set up dedicated demo workspaces with the "demo-", "poc-", or "test-" prefix in the URL
- Test with dry run first: Use
dry_run=Trueto validate operations before execution - Monitor rate limits: Be aware of Braze API rate limits for your workspace
- Use confirmation for destructive ops: Operations like
delete_userrequireconfirm=True - Review logs: Check logs regularly for unexpected behavior
Differences from Official Braze MCP
This server extends the official read-only Braze MCP server with:
- Write operations for campaigns, canvas, users, catalogs, and content blocks
- Comprehensive safety mechanisms to prevent accidental production writes
- Rate limiting to prevent API abuse
- Dry run mode for testing
- Enhanced logging and audit trails
License
MIT License - See LICENSE file for details
Disclaimer
This is a developer tool for creating demos and POCs. Use with caution and always verify your workspace configuration before enabling write operations.