{"_id":"@cashtokenai/meta-mcp-server","name":"@cashtokenai/meta-mcp-server","dist-tags":{"latest":"1.0.0"},"versions":{"1.0.0":{"name":"@cashtokenai/meta-mcp-server","description":"Read-only Model Context Protocol server for Meta Business Manager — Pages, Instagram, Ads insights, Pixels, Catalog, WhatsApp.","version":"1.0.0","author":{"name":"Stephen A."},"license":"MIT","homepage":"https://github.com/feladeveloper/meta-mcp-server#readme","repository":{"type":"git","url":"git+https://github.com/feladeveloper/meta-mcp-server.git"},"bugs":{"url":"https://github.com/feladeveloper/meta-mcp-server/issues"},"keywords":["mcp","model-context-protocol","meta","facebook","instagram","marketing-api","ads","ads-insights","pixels","catalog","whatsapp","business-manager","read-only","ai-tools","claude"],"type":"module","main":"dist/index.js","bin":{"meta-business-manager-mcp-server":"dist/index.js"},"engines":{"node":">=20.10.0"},"scripts":{"build:clean":"rm -rf dist","build:compile":"tsc --project tsconfig.build.json","build:chmod":"chmod +x dist/index.js || true","build":"npm run build:clean && npm run build:compile && npm run build:chmod","start":"node dist/index.js","dev":"tsx src/index.ts","inspect":"npm run build && npx @modelcontextprotocol/inspector dist/index.js","check:types":"tsc --noEmit --project tsconfig.json","test:readonly":"npm run build && node tests/read-only-guard.mjs","test:placeholder":"npm run build && node tests/placeholder-rejection.mjs","test:invariants":"npm run test:readonly && npm run test:placeholder","test:scenarios":"npm run build && node tests/scenarios.mjs","test":"node --experimental-vm-modules node_modules/jest/bin/jest.js","prepublishOnly":"npm run check:types && npm run test:invariants"},"dependencies":{"@modelcontextprotocol/sdk":"^1.11.2","axios":"^1.7.7","lru-cache":"^11.1.0","pino":"^9.5.0","zod":"^3.23.8"},"devDependencies":{"@jest/globals":"^30.0.0","@types/jest":"^30.0.0","@types/node":"^22.0.0","jest":"^30.0.0","ts-jest":"^29.2.0","tsx":"^4.19.0","typescript":"^5.6.0"},"gitHead":"5073d18ce48068173be02faa22422f414b5b6f9b","types":"./dist/index.d.ts","_id":"@cashtokenai/meta-mcp-server@1.0.0","_nodeVersion":"24.14.0","_npmVersion":"11.9.0","dist":{"integrity":"sha512-OpgWulSKcJLuKMjOJdBKOx41hP0AnROQkx8pwuW4Vzvft1XNyPrI6UJAgoguxPYxnGymU/6N2aMvF+ttx6DvYg==","shasum":"af69cd1180c07422f3d77e9dd54ad6673453afa5","tarball":"https://registry.npmjs.org/@cashtokenai/meta-mcp-server/-/meta-mcp-server-1.0.0.tgz","fileCount":109,"unpackedSize":274906,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEYCIQDCqfOsOug0GrKpylFh9OvwUgdPesR0B90gkmoAt1hc6gIhAPiOabVghplqdYP3RsuOw6oqP0G23MvB54Ez/kxF2D8x"}]},"_npmUser":{"name":"cashtokenai","email":"cashtokenai@gmail.com"},"directories":{},"maintainers":[{"name":"cashtokenai","email":"cashtokenai@gmail.com"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/meta-mcp-server_1.0.0_1788794672931_0.48031139126315203"},"_hasShrinkwrap":false}},"time":{"created":"2026-09-07T15:24:32.760Z","1.0.0":"2026-09-07T15:24:33.074Z","modified":"2026-09-07T15:24:33.250Z"},"maintainers":[{"name":"cashtokenai","email":"cashtokenai@gmail.com"}],"description":"Read-only Model Context Protocol server for Meta Business Manager — Pages, Instagram, Ads insights, Pixels, Catalog, WhatsApp.","homepage":"https://github.com/feladeveloper/meta-mcp-server#readme","keywords":["mcp","model-context-protocol","meta","facebook","instagram","marketing-api","ads","ads-insights","pixels","catalog","whatsapp","business-manager","read-only","ai-tools","claude"],"repository":{"type":"git","url":"git+https://github.com/feladeveloper/meta-mcp-server.git"},"author":{"name":"Stephen A."},"bugs":{"url":"https://github.com/feladeveloper/meta-mcp-server/issues"},"license":"MIT","readme":"# meta-mcp-server\n\n> **Read-only Model Context Protocol server for Meta Business Manager.** Plug-in for AI assistants (\"ChatGPT for marketing insights\") that surfaces Pages, Instagram Business, Marketing API ad insights, Pixels, Commerce catalogs, and WhatsApp Business data — all read-only by construction.\n\n[![Read-Only Verified](https://img.shields.io/badge/safety-read--only-success)](#read-only-by-construction)\n[![Governance: Cashtoken SDGP](https://img.shields.io/badge/governance-cashtoken%20sdgp-blue)](./governance/standards/sdgp-main.md)\n[![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](./LICENSE)\n\n---\n\n## Why this exists\n\nCashToken Marketing operates several Pages, Instagram Business accounts, Meta ad accounts, Pixels and (in future) Catalogs / WhatsApp Business assets across the `Hodusoft` Business Manager. Insight retrieval today is fragmented across Business Suite UIs, Ads Manager exports, and ad-hoc Graph API calls. This MCP server consolidates **read-only** access into a single tool surface that any MCP-aware AI assistant can plug into — turning fragmented UIs into one conversational interface for the marketing team.\n\n---\n\n## Read-only by construction\n\nThis server cannot write to Meta. Period. Four layers of defence:\n\n1. **HTTP interceptor** — every axios request passes through a guard that throws `ReadOnlyViolationError` if the method isn't `GET`, before the request leaves the process. ([`src/helpers/graph-client.ts`](./src/helpers/graph-client.ts))\n2. **No write API surface** — the `GraphClient` class exposes only `get()` and `getAllPages()`. No `post()`, `put()`, `patch()`, or `delete()` exist anywhere in `src/`.\n3. **All tools annotated** `readOnlyHint: true, destructiveHint: false` — MCP clients surface this to end users.\n4. **Belt-and-braces token scopes** (operator responsibility) — issue the system-user token with read-only scopes (`ads_read`, `pages_read_engagement`, `read_insights`, `instagram_basic`, `instagram_manage_insights`). Even if the server were compromised, the token itself cannot write. See [`ADR-20260421-Read-Only-HTTP-Enforcement.md`](./governance/project-docs/adr/ADR-20260421-Read-Only-HTTP-Enforcement.md).\n\nVerify any time:\n\n```bash\nnpm run test:readonly\n```\n\n---\n\n## Tools (36)\n\n| Domain | Tools |\n|---|---|\n| **Discovery** (6) | `meta_token_inspect`, `meta_health_check`, `meta_graph_read`, `meta_business_list`, `meta_business_list_assets`, `meta_business_list_system_users` |\n| **Ads / Marketing API** (8) | `meta_ads_list_accounts`, `meta_ads_get_account`, `meta_ads_list_campaigns`, `meta_ads_list_adsets`, `meta_ads_list_ads`, `meta_ads_get_insights` ⭐, `meta_ads_get_creative`, `meta_ads_list_custom_audiences` |\n| **Pages** (7) | `meta_page_list`, `meta_page_get`, `meta_page_list_posts`, `meta_page_get_post_insights`, `meta_page_get_insights`, `meta_page_list_reviews`, `meta_page_list_videos` |\n| **Instagram** (5) | `meta_ig_list_accounts`, `meta_ig_get_account`, `meta_ig_list_media`, `meta_ig_get_media_insights`, `meta_ig_get_audience_demographics` |\n| **Pixels** (2) | `meta_pixel_list`, `meta_pixel_get_stats` |\n| **Catalog** (3) | `meta_catalog_list`, `meta_catalog_list_products`, `meta_catalog_get_diagnostics` |\n| **WhatsApp** (4) | `meta_whatsapp_list_wabas`, `meta_whatsapp_list_phone_numbers`, `meta_whatsapp_list_templates`, `meta_whatsapp_get_analytics` |\n| **Eagle's-eye** (1) | `meta_business_overview` ⭐⭐⭐ — single-call consolidated snapshot across the whole business |\n\n---\n\n## Quickstart\n\n### 1. Install\n\n```bash\ngit clone git@github.com:feladeveloper/meta-mcp-server.git\ncd meta-mcp-server\nnpm install\n```\n\n### 2. Configure environment\n\nCopy `.env.example` → `.env` and fill in:\n\n```bash\nMETA_ACCESS_TOKEN=...        # System-user token (see Token Provisioning below)\nMETA_APP_SECRET=...          # App secret of the app that issued the token (Hodusoft app: 193481170220592)\nMETA_API_VERSION=v23.0\nMETA_CACHE_TTL_SECONDS=120\nMETA_MAX_AUTO_PAGES=5\nLOG_LEVEL=info\n```\n\nOptional allowlists (if set, the server refuses to operate on IDs outside the allowlist):\n\n```bash\nMETA_ALLOWED_BUSINESS_IDS=133767790806312\nMETA_ALLOWED_AD_ACCOUNT_IDS=act_146517954996436,...\nMETA_ALLOWED_PAGE_IDS=138368686823692,...\nMETA_ALLOWED_IG_USER_IDS=17841406467396631,...\n```\n\n### 3. Build and run\n\n```bash\nnpm run build\nnode dist/index.js   # stdio MCP server\n```\n\nOr in development:\n\n```bash\nnpm run dev\n```\n\nFor an MCP Inspector session against the built server:\n\n```bash\nnpm run inspect\n```\n\n### 4. Wire into a client\n\nExample (Claude Desktop or any MCP client) — fetches the published package on demand via `npx`:\n\n```json\n{\n  \"mcpServers\": {\n    \"meta\": {\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"@cashtokenai/meta-mcp-server\"],\n      \"env\": {\n        \"META_ACCESS_TOKEN\": \"...\",\n        \"META_APP_SECRET\": \"...\"\n      }\n    }\n  }\n}\n```\n\nFor a global install (`npm install -g @cashtokenai/meta-mcp-server`), use the bin directly:\n\n```json\n{\n  \"mcpServers\": {\n    \"meta\": {\n      \"command\": \"meta-business-manager-mcp-server\",\n      \"env\": {\n        \"META_ACCESS_TOKEN\": \"...\",\n        \"META_APP_SECRET\": \"...\"\n      }\n    }\n  }\n}\n```\n\nFor local development against a clone of this repo:\n\n```json\n{\n  \"mcpServers\": {\n    \"meta\": {\n      \"command\": \"node\",\n      \"args\": [\"/absolute/path/to/meta-mcp-server/dist/index.js\"],\n      \"env\": {\n        \"META_ACCESS_TOKEN\": \"...\",\n        \"META_APP_SECRET\": \"...\"\n      }\n    }\n  }\n}\n```\n\n---\n\n## Token Provisioning (Cashtoken-specific)\n\nThe system user `AI_Insights_Reader` (id `122093391782492654`) under the `Hodusoft` business (id `133767790806312`) is the canonical identity for this server. Procedure to issue / rotate its token:\n\n1. Business Settings → System Users → `AI_Insights_Reader` → **Generate New Token**\n2. Pick the **Hodusoft** app (id `193481170220592`)\n3. In the scope picker, untick everything, then tick:\n   - `business_management`, `ads_management` (Meta only exposes management here; server still blocks writes), `pages_read_engagement`, `pages_read_user_content`, `read_insights`, `instagram_basic`, `instagram_manage_insights`, `whatsapp_business_management`, `catalog_management`\n4. Copy the token (Meta only shows it once)\n5. Paste over `META_ACCESS_TOKEN` in `.env`\n6. Verify with `meta_health_check` and `meta_token_inspect`\n\nToken TTL is ~60 days. Set a calendar reminder; rotation procedure documented in [`/governance/project-docs/runbook.md`](./governance/project-docs/runbook.md).\n\nSee also: [`ADR-20260421-System-User-Token-Pattern.md`](./governance/project-docs/adr/ADR-20260421-System-User-Token-Pattern.md).\n\n---\n\n## Repository layout\n\n```\nmeta-mcp-server/\n├── CLAUDE.md                          # AI agent rules (governance)\n├── .cursorrules                       # Cursor agent rules\n├── .github/\n│   ├── copilot-instructions.md        # Copilot agent rules\n│   ├── ISSUE_TEMPLATE/\n│   └── workflows/                     # CI/CD (GitHub Actions, Sentinel status check)\n├── .claude/skills/                    # 23 governance skills (scaffolding, review, git-ops, …)\n├── .sentinelrc                        # Sentinel governance plugin config\n├── CHANGELOG.md                       # SemVer release history\n├── README.md\n├── governance/                        # Governance assets — see /governance/standards/\n│   ├── standards/                     # SDGP policies, coding standards\n│   ├── templates/                     # Doc templates (specs, ADRs, deviations, project docs)\n│   └── project-docs/                  # Project documents\n│       ├── 1-vision-doc.md\n│       ├── 2-brd.md\n│       ├── 3-prd.md\n│       ├── 5-tad.md\n│       ├── runbook.md\n│       ├── solution-doc-architecture.md\n│       ├── specs/                     # Feature specs\n│       ├── adr/                       # Architecture Decision Records\n│       └── deviations/                # Governance deviation logs\n├── src/                               # Implementation (see TAD)\n│   ├── index.ts                       # stdio entrypoint\n│   ├── server.ts                      # MCP server wiring\n│   ├── config.ts                      # env + allowlists\n│   ├── errors.ts                      # MetaError, ReadOnlyViolationError\n│   ├── logger.ts                      # pino, stderr only, redacts secrets\n│   ├── constants.ts\n│   ├── context.ts\n│   ├── helpers/\n│   │   ├── graph-client.ts            # GET-only axios client + retry + cache + appsecret_proof\n│   │   ├── cache.ts                   # LRU TTL cache\n│   │   ├── format.ts                  # JSON / Markdown response formatting\n│   │   └── schema.ts                  # Shared Zod shapes (pagination, date presets, IDs)\n│   ├── tools/                         # 36 tool implementations grouped by domain\n│   │   ├── token/  meta/  business/  ads/  pages/  instagram/  pixels/  catalog/  whatsapp/  overview/\n│   │   ├── shared.ts                  # runList / runGet / errorResult helpers\n│   │   └── register.ts                # Centralized tool registration\n│   └── types/\n└── tests/\n    └── read-only-guard.mjs            # Runtime proof that POST/PUT/PATCH/DELETE are blocked\n```\n\n---\n\n## Governance\n\nThis project is initialized from the [`cashtokenrewards/project-governance-template`](https://github.com/cashtokenrewards/project-governance-template) and follows the **Software Development Governance Policy (SDGP)** in [`/governance/standards/sdgp-main.md`](./governance/standards/sdgp-main.md).\n\n**Three absolute rules:**\n1. No feature is built without an approved spec. ([`/governance/project-docs/specs/`](./governance/project-docs/specs/))\n2. No ADR is written without a parent feature spec. ([`/governance/project-docs/adr/`](./governance/project-docs/adr/))\n3. No implementation begins without the spec and all required ADRs approved.\n\nThe current implementation (commit zero) was bootstrapped against an initial pass of governance docs:\n\n| Doc | Path |\n|---|---|\n| Vision | [`governance/project-docs/1-vision-doc.md`](./governance/project-docs/1-vision-doc.md) |\n| BRD | [`governance/project-docs/2-brd.md`](./governance/project-docs/2-brd.md) |\n| PRD | [`governance/project-docs/3-prd.md`](./governance/project-docs/3-prd.md) |\n| TAD | [`governance/project-docs/5-tad.md`](./governance/project-docs/5-tad.md) |\n| Runbook | [`governance/project-docs/runbook.md`](./governance/project-docs/runbook.md) |\n| Meta setup runbook | [`governance/project-docs/runbook-meta-setup.md`](./governance/project-docs/runbook-meta-setup.md) |\n| Add-a-business runbook | [`governance/project-docs/runbook-add-business.md`](./governance/project-docs/runbook-add-business.md) |\n| Specs | [`governance/project-docs/specs/`](./governance/project-docs/specs/) |\n| ADRs | [`governance/project-docs/adr/`](./governance/project-docs/adr/) |\n| Deviations | [`governance/project-docs/deviations/`](./governance/project-docs/deviations/) |\n\n**Branch model:** Gitflow. `main` (production), `dev` (integration). Short-lived branches: `feature-`, `fix-`, `release-`, `hotfix-`, `docs-`. All merges `--no-ff`. See [`/governance/standards/sdgp-main.md`](./governance/standards/sdgp-main.md) §7.4.\n\n**AI agent rules:** [`CLAUDE.md`](./CLAUDE.md), [`.cursorrules`](./.cursorrules), [`.github/copilot-instructions.md`](./.github/copilot-instructions.md). Sentinel keeps these in sync with the central governance config.\n\n---\n\n## Sentinel\n\nThis repository is tracked by the [Sentinel governance plugin](https://github.com/feladeveloper/sentinel-claude-plugin). Configuration lives at [`.sentinelrc`](./.sentinelrc). On any clone:\n\n```bash\nexport SENTINEL_GITHUB_TOKEN=\"ghp_...\"     # Personal access token with repo:read\nsentinel sync                               # Pull latest org-level governance into CLAUDE.md\n```\n\n`/sentinel-sync` and `/sentinel-status` slash commands are also available inside Claude Code once the plugin is installed.\n\n---\n\n## Scripts\n\n| Script | What it does |\n|---|---|\n| `npm run build` | Clean + compile TypeScript → `dist/` |\n| `npm run dev` | Run with `tsx` (no build step) |\n| `npm run start` | Run built `dist/index.js` |\n| `npm run inspect` | Build + open MCP Inspector |\n| `npm run check:types` | `tsc --noEmit` |\n| `npm run test:readonly` | Build + runtime proof that POST/PUT/PATCH/DELETE are blocked by the Graph client |\n| `npm test` | (placeholder for jest suite — see [`SPEC-07-eval-suite.md`](./governance/project-docs/specs/) when added) |\n\n---\n\n## Status\n\n| Aspect | State |\n|---|---|\n| Implementation | **v0.1.0 — bootstrapped, 36 tools, build clean, read-only guard verified** |\n| Governance docs | Initial pass — Vision / BRD / PRD / TAD / Runbook / 3 ADRs / 1 deviation drafted |\n| App-level (Meta) | Hodusoft app in **development tier** for Marketing API. Standard Access via App Review pending. |\n| Asset coverage | All 3 Pages discoverable; 1 Page (CashToken) currently assigned to AI_Insights_Reader; 5 ad accounts visible; 3 Pixels visible; 1 IG (cashtokenhq) discovered via Page link |\n| Open scopes | `read_insights`, `instagram_manage_insights`, `whatsapp_business_management`, `catalog_management` may need to be added to the Hodusoft app before they appear in the token picker |\n\n---\n\n## License\n\nMIT — see [LICENSE](./LICENSE).\n","readmeFilename":"README.md","_rev":"1-6af9780fbae9d52f6fb0042db9f72956"}