Buddy Docs

Use Buddy's Tools over MCP

Last updated: 2026-10-18

Buddy's hosted MCP server lets an AI client you already use, such as Claude, Cursor, or the Gemini CLI, call Buddy's Google Ads tools directly, signed in as you. If you want everything to run on your own machine with your own Google Ads API credentials instead, use the self-hosted setup.

1. Get your connection token

The server authenticates with your Buddy sign-in. Sign in to Buddy, then come back to this page in the same browser:

Checking whether you are signed in…

Treat the token like a password. Anyone who has it can use Buddy on your Google Ads accounts. It stops working when you sign out of Buddy or after 90 days, whichever comes first; signing in again issues a new one.

2. Add the server to your client

Server address (streamable HTTP):

https://buddy-agent.john-fae.workers.dev/mcp

Every request must send Authorization: Bearer YOUR_TOKEN. Replace YOUR_TOKEN below with the token from step 1.

Claude Code

claude mcp add --transport http buddy https://buddy-agent.john-fae.workers.dev/mcp \
          --header "Authorization: Bearer YOUR_TOKEN"

Cursor

Add to ~/.cursor/mcp.json (or .cursor/mcp.json in a project):

{
          "mcpServers": {
            "buddy": {
              "url": "https://buddy-agent.john-fae.workers.dev/mcp",
              "headers": { "Authorization": "Bearer YOUR_TOKEN" }
            }
          }
        }

Gemini CLI

Add to ~/.gemini/settings.json:

{
          "mcpServers": {
            "buddy": {
              "httpUrl": "https://buddy-agent.john-fae.workers.dev/mcp",
              "headers": { "Authorization": "Bearer YOUR_TOKEN" }
            }
          }
        }

Claude Desktop

Claude Desktop's config file starts local servers, so bridge to the remote one with mcp-remote (needs Node.js). In claude_desktop_config.json: 

{
          "mcpServers": {
            "buddy": {
              "command": "npx",
              "args": ["-y", "mcp-remote", "https://buddy-agent.john-fae.workers.dev/mcp",
                       "--header", "Authorization:${BUDDY_AUTH}"],
              "env": { "BUDDY_AUTH": "Bearer YOUR_TOKEN" }
            }
          }
        }

Clients that only speak the older SSE transport can use https://buddy-agent.john-fae.workers.dev/sse with the same header.

3. Pick an account, then ask

Start by asking your client to call configure_account with a customer ID your Google login can reach. If you manage several accounts, use your manager account's ID, call discover_accounts to list the accounts under it, then call configure_account again with the one you want. After that, ask normally: "pull last month's campaign performance", "run an account health check".

Available tools

Tool What it does
configure_account Choose the Google Ads account (customer ID) for this session.
discover_accounts List the accounts under the configured manager account.
pull_google_ads_data Run any of 90+ built-in reports with an optional date range.
account_health Quick health check of the configured account.
compare_performance Compare two periods.
generate_keyword_ideas Keyword ideas from Google's Keyword Planner.
pull_search_console Search Console sites and search analytics, read-only.
scan_url Check a landing page for tracking tags and basic issues.
calculate_ads_math ROAS, CPA, break-even and similar calculations.
execute_google_ads_write Make a change. The first call only previews it; it runs on a second call after you confirm.

Each tool can be called up to 10 times a minute per session.

If it doesn't connect

Something here wrong or out of date? Tell us and we will fix the page.