Metadata-Version: 2.5
Name: excutia
Version: 0.2.0
Summary: Local MCP server for Google Ads, Meta Ads and GA4: read performance, size and call tests, and change accounts only through approved plans.
Project-URL: Homepage, https://excutia.com
Project-URL: Repository, https://github.com/excutia/ads-mcp
Project-URL: Issues, https://github.com/excutia/ads-mcp/issues
Author: Stephen Dang
License-Expression: Apache-2.0
License-File: LICENSE
Keywords: advertising,claude-code,codex,ga4,google-ads,mcp,meta-ads
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Operating System :: MacOS
Classifier: Operating System :: POSIX :: Linux
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Office/Business
Requires-Python: >=3.12
Requires-Dist: google-ads<33,>=32
Requires-Dist: httpx>=0.27
Requires-Dist: keyring>=25.6
Requires-Dist: mcp<2.4,>=2.3
Requires-Dist: pydantic<3,>=2.11
Requires-Dist: python-dotenv>=1.0
Requires-Dist: statsmodels>=0.15
Description-Content-Type: text/markdown

# Excutia ads MCP

A local MCP server and plugin for Claude Code and Codex that reads Google Ads, Meta Ads and GA4,
sizes and calls ad tests honestly, and changes accounts only through change plans you approve.

It runs on your machine with your own credentials and your own Google Cloud project. It makes no
LLM or paid API calls: your assistant does the reasoning, and code computes every number.

> Early release. The commands below work once `excutia` 0.2.0 is published to PyPI.

## Install

Claude Code:

```
/plugin install excutia --marketplace excutia/ads-mcp
```

or, from a shell: `claude plugin marketplace add excutia/ads-mcp` then `claude plugin install excutia@excutia`.

Codex:

```bash
codex plugin marketplace add excutia/ads-mcp
```

```bash
codex plugin add excutia@excutia
```

Codex runs a plugin's hooks only after you trust them; until then Excutia works without its memory hooks.

Only the MCP server, without skills or experts:

```bash
claude mcp add excutia -- uvx excutia==0.2.0
```

```bash
codex mcp add excutia -- uvx excutia==0.2.0
```

The plugins and these commands launch the pinned package with [uv](https://docs.astral.sh/uv/)'s
`uvx`, so uv must be installed.

## Try it without an account

With no workspace configured, Excutia serves a demo workspace of invented data. Ask your assistant
"Diagnose my Google Ads account" or "How did my campaigns do last week?". Nothing reaches an ad
platform in the demo, and change plans refuse to apply.

## Connect your accounts

```bash
uvx excutia==0.2.0 setup
```

Setup walks through your own Google Cloud project (enable the Google Ads API, publish the OAuth
consent screen to In production, create a Desktop OAuth client, sign in on a 127.0.0.1 redirect),
a Meta system-user token and a GA4 property. Developer tokens are not needed: Google sunset them on
9 Sep 2026, and API access now follows your Cloud project. Secrets go to the OS keychain; Claude Code
users can also enter them as plugin options, which Claude Code keeps in its secure storage.

Check credentials and access at any time; each failure prints the exact fix:

```bash
uvx excutia==0.2.0 doctor
```

## What it runs and contacts

- `uvx` downloads the `excutia` package and its dependencies from PyPI.
- The server reads and, only after you approve a change plan, writes through the Google Ads API
  (v25), the Meta Graph API (v26.0) and the GA4 Data and Admin APIs, using your OAuth tokens.
- `setup` and `doctor` call Google's OAuth endpoints and the read-only checks above.
- Creative previews are fetched from the platforms' image CDNs (fbcdn.net, googlesyndication.com,
  googleusercontent.com).
- Review pages are served on 127.0.0.1 only.
- Data is stored in SQLite under `~/.excutia/<workspace>/`. There is no telemetry.

## Development

```bash
uv sync
```

```bash
uv run pytest
```

## License

Apache-2.0. See [LICENSE](LICENSE).
