Docs · MCP clients

Use AdRails with Grok, Claude Code, Cursor and other MCP clientsOne local stdio command, four clients · adrails.dev

Direct answer. AdRails is a local MCP server that speaks JSON-RPC 2.0 over stdio, so any client that can launch a local command can run it: point the client at python3 -m adsops --config /absolute/path/config.json. Grok, Claude Code and Cursor each register that command in one step. There is no URL to add, because AdRails is never hosted: it runs on your machine with your own Google Cloud project and credentials.

Last tested with AdRails 0.2.2 · Python 3 · macOS and Linux · Apache-2.0 · local stdio, no hosted endpoint
What you need first

What the client has to support

  • Launching a local process — AdRails is a command plus args, not a remote URL.
  • stdio transport — JSON-RPC 2.0, one object per line. Diagnostics go to stderr and stay separate from the protocol stream.
  • Nothing else — no hosted endpoint, no OAuth handshake with AdRails, no account. Google credentials are yours and are read from the config: a service-account JSON file, a static token, or a secret-manager lookup.
  • The package on the same machine — pipx install git+https://github.com/antonioac1/adrails (the PyPI release is coming soon), or point command at the interpreter inside the pipx/uvx environment.
Client 1

Grok CLI

Grok adds a stdio server with mcp add, then everything after -- is the command AdRails runs.

shell · Grok CLIstdio server
grok mcp add adrails -- python3 -m adsops --config /abs/path/config.json
grok mcp doctor adrails      # checks the entry resolves and the server starts

Grok also reads ~/.claude.json, .cursor/mcp.json and a project .mcp.json, so an adrails entry you added for Claude Code or Cursor is picked up without adding it twice.

Client 2

Claude Code

The same command, registered with the Claude Code CLI instead of a JSON file.

shell · Claude Codestdio server
claude mcp add adrails -- python3 -m adsops --config /abs/path/config.json

Step-by-step instructions, including the config file and the first validated plan: install AdRails with Claude Code.

Running AdRails beside Google's official read-only google-ads-mcp is one entry each in the same client: with Google Ads MCP.

Client 3

Cursor, and any client that reads .mcp.json

Cursor uses ~/.cursor/mcp.json for every project or .cursor/mcp.json for one; the generic project form is .mcp.json at the repository root. All three take the same object, with command and args:

~/.cursor/mcp.json · .cursor/mcp.json · .mcp.json
{
  "mcpServers": {
    "adrails": {
      "command": "python3",
      "args": ["-m", "adsops", "--config", "/abs/path/config.json"]
    }
  }
}

Use an absolute path for the config file: the client may launch the process from a different working directory than your shell. Paths inside the config are ~-expanded at load time, but the --config path itself should be absolute.

Some clients accept a "type": "stdio" field alongside command; it is optional here, since a command plus args is what makes the server local.

Why

Why there is no remote URL

A URL-shaped entry points at a hosted MCP endpoint that holds the Google credentials somewhere else. AdRails has no such endpoint, by design.

AdRails is built so each business uses its own Google Cloud project and its own API access, with credentials that never leave its machine. That is why AdRails always runs on your machine, against your own Google Cloud project, your own developer token and your own service account. The only endpoint the package talks to is the Google Ads API.

  • No proxy, no token custody — nobody at AdRails holds a token for your account, because there is no AdRails server to hold it.
  • Nothing to sign up for — no AdRails account, no API key, no seat.
  • No remote transport to configure — a client that only supports remote or HTTP MCP servers cannot run AdRails, and no URL will change that.
  • Apache-2.0 — the executor is free to run, and the code you run is the code in the repository.
Checklist

Before you connect an agent

  • commit_policy defaults to require_clean_git: true and allow_commit: false — leave them there until you have watched a plan.
  • allow_enable defaults to false, so no plan can set a campaign to ENABLED.
  • Set max_guard_age_min so a stale guard heartbeat blocks exposure-increasing changes.
  • Schedule guard-all every 15 minutes from launchd, systemd or cron. The guard is a separate scheduled job, not something the MCP session runs.
  • Turn on require_plan_id if you want every commit to quote the exact plan shown.
  • Run python3 -m adsops --selftest in the same environment the client will use: if the self test fails there, the MCP client will fail too.

Refusals such as plan_id required, outside guard range or an error naming allow_set are the rails working. Check that your client surfaces tool errors verbatim, because the agent needs to see them.

FAQ

MCP client questions

Does AdRails need a Grok API key or an AdRails account?

No AdRails account and no AdRails key. The client launches a local process with grok mcp add adrails -- python3 -m adsops --config /abs/path/config.json; the only credentials involved are the Google Ads ones in your config file.

Does Grok read the same MCP config as Claude Code and Cursor?

Yes. Grok reads ~/.claude.json, .cursor/mcp.json and a project .mcp.json as well as its own configuration, so an adrails entry added for Claude Code or Cursor is picked up without a second command.

Is there a hosted AdRails endpoint I can add by URL?

No. AdRails does not host anything and does not proxy Google calls, which is also why Google's prohibition on hosted Ads MCP wrappers does not apply to it.

Where is AdRails listed?

MCP Registry name dev.adrails/adrails (0.2.0). The current source release on GitHub is 0.2.2, so the registry entry lags the source release.