{"_id":"@channel47/meta-ads-mcp","name":"@channel47/meta-ads-mcp","dist-tags":{"beta":"1.0.0","latest":"1.0.0"},"versions":{"1.0.0":{"name":"@channel47/meta-ads-mcp","version":"1.0.0","description":"Meta Ads MCP Server - Query and mutate Meta/Facebook/Instagram ads data via Graph API","main":"server/index.js","bin":{"meta-ads-mcp":"server/index.js"},"type":"module","scripts":{"start":"node server/index.js","test":"node --test *.test.js test/*.test.js","prepublishOnly":"npm test"},"keywords":["mcp","model-context-protocol","meta-ads","facebook-ads","instagram-ads","analytics","advertising","claude"],"author":{"name":"channel47"},"license":"MIT","repository":{"type":"git","url":"git+https://github.com/channel47/mcps.git","directory":"meta-ads"},"bugs":{"url":"https://github.com/channel47/mcps/issues"},"homepage":"https://github.com/channel47/mcps/tree/main/meta-ads#readme","dependencies":{"@modelcontextprotocol/sdk":"^1.29.0"},"engines":{"node":">=18.0.0"},"_id":"@channel47/meta-ads-mcp@1.0.0","gitHead":"b40ed5fec586628f184bd1fecd8838760b4e67e9","_nodeVersion":"24.1.0","_npmVersion":"11.3.0","dist":{"integrity":"sha512-QDWS/lgJD23vFDptmxGUV+WiyFoo0T1myulZqqHfQk+fykpZaMHUSZgWdZnTpUNROCENMo8Mdy74crRlKYmwvw==","shasum":"ffa1191993e5fc4b6a5230b6b6e0b93df80e5f2a","tarball":"https://registry.npmjs.org/@channel47/meta-ads-mcp/-/meta-ads-mcp-1.0.0.tgz","fileCount":20,"unpackedSize":52520,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEYCIQDjJf56AIBLZ6jptMDrLBiBTOTdKIdKTY38xR1LwV3VOQIhAMjjh//bHqghK+S2rmodZxGCEPUy0yWZEfSIAUEgMyKq"}]},"_npmUser":{"name":"ctrlswing","email":"jacksondean.me@gmail.com"},"directories":{},"maintainers":[{"name":"ctrlswing","email":"jacksondean.me@gmail.com"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/meta-ads-mcp_1.0.0_1783745128556_0.5801104550329808"},"_hasShrinkwrap":false}},"time":{"created":"2026-07-11T04:45:28.383Z","1.0.0":"2026-07-11T04:45:28.681Z","modified":"2026-07-11T04:45:28.911Z"},"maintainers":[{"name":"ctrlswing","email":"jacksondean.me@gmail.com"}],"description":"Meta Ads MCP Server - Query and mutate Meta/Facebook/Instagram ads data via Graph API","homepage":"https://github.com/channel47/mcps/tree/main/meta-ads#readme","keywords":["mcp","model-context-protocol","meta-ads","facebook-ads","instagram-ads","analytics","advertising","claude"],"repository":{"type":"git","url":"git+https://github.com/channel47/mcps.git","directory":"meta-ads"},"author":{"name":"channel47"},"bugs":{"url":"https://github.com/channel47/mcps/issues"},"license":"MIT","readme":"# @channel47/meta-ads-mcp\n\nMCP server for Meta Ads (Facebook + Instagram) using the Graph API (`v25.0`).\n\nThis server exposes three tools expected by channel47 Meta workflows:\n\n- `list_accounts`\n- `query`\n- `mutate`\n\n## Installation\n\n### Standalone\n\n```bash\nnpx @channel47/meta-ads-mcp@latest\n```\n\n### Monorepo Development\n\n```bash\ncd mcps\nnpm install\nnpm run test\n```\n\n## Configuration\n\n### Required\n\n| Variable | Description |\n|----------|-------------|\n| `META_ADS_ACCESS_TOKEN` | Meta Graph API access token (long-lived user token or system user token) |\n\n### Optional\n\n| Variable | Description |\n|----------|-------------|\n| `META_ADS_ACCOUNT_ID` | Default ad account ID used when `account_id` is omitted |\n| `META_ADS_READ_ONLY` | Set to `true` to disable live mutations |\n| `META_ADS_REQUEST_TIMEOUT_MS` | HTTP request timeout in milliseconds (default `30000`) |\n\n## Tool Reference\n\n### `list_accounts`\n\nList accessible ad accounts from `GET /me/adaccounts`.\n\n**Params:**\n- `status` (optional): status filter (`ACTIVE`, `DISABLED`, etc.)\n\n**Notes:**\n- Account IDs are normalized without `act_` prefix\n- Includes raw `account_status` and mapped status text\n- Follows Graph API cursor pagination to return all accessible accounts\n\n### `query`\n\nStructured query wrapper for Meta Graph API entities:\n\n- `campaigns`\n- `adsets`\n- `ads`\n- `insights`\n- `audiences`\n- `creatives`\n\n**Core params:**\n- `entity` (required)\n- `account_id` (optional if `META_ADS_ACCOUNT_ID` exists)\n- `fields`, `filters`, `sort`, `limit`\n- `inline_insights_fields` (optional on non-`insights` entities): appends nested inline projection like `insights{spend,ctr,frequency}`\n\n**Insights params:**\n- `date_range`: preset (`today`, `yesterday`, `last_7d`, `last_14d`, `last_30d`, `this_month`, `this_week_mon_today`, `last_quarter`) or `{ since, until }`\n- `level`: `campaign`, `adset`, or `ad`\n- `time_increment`: `1`, `7`, `monthly`, etc.\n- `breakdowns`: array of dimensions (`age`, `gender`, `publisher_platform`, etc.)\n\n### `mutate`\n\nMutation tool with dry-run safety by default.\n\n**Operation format:**\n\n```json\n{\n  \"entity\": \"campaign\",\n  \"action\": \"update\",\n  \"id\": \"123456789\",\n  \"params\": {\n    \"daily_budget\": \"5000\"\n  }\n}\n```\n\n**Supported entities:**\n- `campaign`\n- `adset`\n- `ad`\n- `audience`\n- `creative`\n\n**Supported actions:**\n- `create`\n- `update`\n- `pause`\n- `enable`\n- `archive`\n- `delete`\n\n**Top-level params:**\n- `operations` (required)\n- `dry_run` (default `true`)\n- `partial_failure` (default `true`)\n\n## Behavior Notes\n\n- Auth is sent via `Authorization: Bearer <token>` request header\n- API retries once on:\n  - HTTP `429`\n  - Graph error codes `17` and `32`\n- For throttled retries, `Retry-After` header is used when available; otherwise fallback is `60s`\n- Requests are aborted on timeout (default `30000ms`, configurable via `META_ADS_REQUEST_TIMEOUT_MS`)\n- Budgets are returned in minor currency units (example: `5000` means `$50.00` USD)\n\n## Development Commands\n\n```bash\ncd meta-ads\nnpm test\nnode server/index.js\n```\n\n## License\n\nMIT\n","readmeFilename":"README.md","_rev":"1-9319cb66914ca0b3c3e30082821c0db0"}