Skip to main content

​
Overview

The ChatAds MCP Wrapper is a Python package that runs locally on your machine and proxies requests to the ChatAds API. Use this if your MCP client requires local stdio-based servers or you need local control over the MCP server.
If your MCP client supports remote HTTP servers, consider using the Native MCP Server instead - no installation required.

​
Requirements

  • Python 3.10+
  • ChatAds API key

​
Installation

pip install chatads-mcp-wrapper

​
Quick Start

​
MCP Client Configuration

Add ChatAds to your MCP client’s configuration. The location varies by client:
Edit your Claude Desktop config:
  • macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
  • Windows: %APPDATA%\Claude\claude_desktop_config.json
  • Linux: ~/.config/Claude/claude_desktop_config.json
{
  "mcpServers": {
    "chatads": {
      "command": "python",
      "args": ["-m", "chatads_mcp_wrapper"],
      "env": {
        "CHATADS_API_KEY": "cak_your_api_key"
      }
    }
  }
}

​
Option 2: Using the chatads-mcp command

First, find where the command was installed: 
which chatads-mcp
Then use the full path: 
{
  "mcpServers": {
    "chatads": {
      "command": "/path/from/which/chatads-mcp",
      "args": [],
      "env": {
        "CHATADS_API_KEY": "cak_your_api_key"
      }
    }
  }
}
Common installation paths:
  • Standard pip: ~/.local/bin/chatads-mcp
  • pyenv: ~/.pyenv/shims/chatads-mcp
  • Homebrew Python: /opt/homebrew/bin/chatads-mcp
  • System Python: /usr/local/bin/chatads-mcp
Restart your MCP client and the tool will be available.

​
Benefits

  • Universal compatibility - Works with any MCP client supporting stdio transport
  • Local control - Runs on your machine, you control the process
  • Circuit breaker - Built-in resilience for network issues
  • Offline caching - Can cache responses locally
  • Debug logging - Full visibility into requests

​
Configuration

​
Environment Variables

VariableDefaultDescription
CHATADS_API_KEY(required)Your ChatAds API key
CHATADS_API_BASE_URLhttps://api.getchatads.comOverride API base URL
CHATADS_MCP_TIMEOUT15Request timeout in seconds
CHATADS_MCP_MAX_RETRIES3Max retry attempts
CHATADS_MCP_BACKOFF0.6Backoff delay between retries
CHATADS_CIRCUIT_BREAKER_THRESHOLD5Failures before circuit opens
CHATADS_CIRCUIT_BREAKER_TIMEOUT60Seconds before retry after circuit opens
LOGLEVELINFOLogging level (DEBUG, INFO, WARNING, ERROR)
CHATADS_LOG_FORMATtextLog format (text or json)

​
Available Tools

​
chatads_message_send

The main tool for fetching affiliate product recommendations.
Response Format: The MCP Wrapper returns the ChatAds API response directly. Key fields:
  • status - Response status: “filled”, “partial_fill”, “no_offers_found”, or “internal_error”
  • offers[] - Array of affiliate offers (snake_case, only contains filled offers)
  • Each offer has: link_text, url, confidence_level
Parameters:
ParameterTypeRequiredDescription
messagestringYesUser message to analyze (1-5000 chars)
ipstringNoIPv4 address for country detection
countrystringNoISO country code (e.g., “US”)
qualitystringNo”fast”, “standard” (default), or “best”
api_keystringNoOverride env var API key
Response: 
{
  "data": {
    "status": "filled",
    "offers": [
      {
        "link_text": "standing desk",
        "url": "https://amazon.com/...",
        "confidence_level": "high"
      }
    ],
    "requested": 1,
    "returned": 1
  },
  "error": null,
  "meta": {
    "request_id": "abc-123"
  }
}

​
Features

​
Circuit Breaker

Prevents retry storms when the API is experiencing issues. After N consecutive failures (default: 5), the circuit breaker “opens” and fails fast for a cooldown period. States:
  • CLOSED - Normal operation
  • OPEN - Failing fast, not attempting requests
  • HALF_OPEN - Testing if service recovered

​
Quota Warnings

The wrapper monitors usage and warns when approaching limits:
  • Monthly quota < 10 requests remaining
  • Daily quota >= 90% used
Warnings appear in metadata.notes and logs.

​
Running Standalone

You can run the wrapper directly for testing: 
# Set API key
export CHATADS_API_KEY=cak_your_api_key

# Run the MCP server
chatads-mcp

# Or with debug logging
LOGLEVEL=DEBUG chatads-mcp

# Or with JSON logging (for production)
CHATADS_LOG_FORMAT=json chatads-mcp

​
Development

​
Install from Source

git clone https://github.com/Chat-Ads/chatads-mcp-wrapper.git
cd chatads-mcp-wrapper
python3 -m venv .venv && source .venv/bin/activate
pip install -r requirements-dev.txt

​
Run Tests

pytest
Tests are async and enforce >= 85% coverage.

​
Troubleshooting

SymptomCauseResolution
CONFIGURATION_ERRORMissing API keySet CHATADS_API_KEY env var
FORBIDDEN / UNAUTHORIZEDInvalid keyVerify key in dashboard
DAILY_LIMIT_EXCEEDEDHit daily capWait or upgrade plan
CIRCUIT_BREAKER_OPENToo many failuresWait 60 seconds
UPSTREAM_UNAVAILABLENetwork/API outageCheck API status, retry later
Tool not appearingCommand not foundUse full path from which chatads-mcp
Enable debug logging for more insight: 
LOGLEVEL=DEBUG chatads-mcp

​
Comparison: Wrapper vs Native Server

FeaturePython WrapperNative Server
InstallationRequiredNone
Transportstdio (local)HTTP (remote)
UpdatesManual pip upgradeAutomatic
Local controlYesNo
Circuit breakerClient-sideServer-side
Offline useCan cache locallyNo

​
Next Steps

Get API Key

Sign up and create your API key

Native Server

Zero-install option for clients supporting HTTP transport