@praise25/meta-mcp-server

v0.1.2

Published

13 days ago

Read-only Model Context Protocol server for Meta Business Manager — Pages, Instagram, Ads insights, Pixels, Catalog, WhatsApp.

Downloads

342

meta-mcp-server

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.

Why this exists

CashToken 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.

Read-only by construction

This server cannot write to Meta. Period. Four layers of defence:

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)
No write API surface — the GraphClient class exposes only get() and getAllPages(). No post(), put(), patch(), or delete() exist anywhere in src/.
All tools annotated readOnlyHint: true, destructiveHint: false — MCP clients surface this to end users.
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.

Verify any time:

npm run test:readonly

Tools (36)

| Domain | Tools | |---|---| | Discovery (6) | meta_token_inspect, meta_health_check, meta_graph_read, meta_business_list, meta_business_list_assets, meta_business_list_system_users | | 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 | | 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 | | Instagram (5) | meta_ig_list_accounts, meta_ig_get_account, meta_ig_list_media, meta_ig_get_media_insights, meta_ig_get_audience_demographics | | Pixels (2) | meta_pixel_list, meta_pixel_get_stats | | Catalog (3) | meta_catalog_list, meta_catalog_list_products, meta_catalog_get_diagnostics | | WhatsApp (4) | meta_whatsapp_list_wabas, meta_whatsapp_list_phone_numbers, meta_whatsapp_list_templates, meta_whatsapp_get_analytics | | Eagle's-eye (1) | meta_business_overview ⭐⭐⭐ — single-call consolidated snapshot across the whole business |

Quickstart

1. Install

git clone [email protected]:feladeveloper/meta-mcp-server.git
cd meta-mcp-server
npm install

2. Configure environment

Copy .env.example → .env and fill in:

META_ACCESS_TOKEN=...        # System-user token (see Token Provisioning below)
META_APP_SECRET=...          # App secret of the app that issued the token (Hodusoft app: 193481170220592)
META_API_VERSION=v23.0
META_CACHE_TTL_SECONDS=120
META_MAX_AUTO_PAGES=5
LOG_LEVEL=info

Optional allowlists (if set, the server refuses to operate on IDs outside the allowlist):

META_ALLOWED_BUSINESS_IDS=133767790806312
META_ALLOWED_AD_ACCOUNT_IDS=act_146517954996436,...
META_ALLOWED_PAGE_IDS=138368686823692,...
META_ALLOWED_IG_USER_IDS=17841406467396631,...

3. Build and run

npm run build
node dist/index.js   # stdio MCP server

Or in development:

npm run dev

For an MCP Inspector session against the built server:

npm run inspect

4. Wire into a client

Example (Claude Desktop or any MCP client) — fetches the published package on demand via npx:

{
  "mcpServers": {
    "meta": {
      "command": "npx",
      "args": ["-y", "@praise25/meta-mcp-server"],
      "env": {
        "META_ACCESS_TOKEN": "...",
        "META_APP_SECRET": "..."
      }
    }
  }
}

For a global install (npm install -g @praise25/meta-mcp-server), use the bin directly:

{
  "mcpServers": {
    "meta": {
      "command": "meta-business-manager-mcp-server",
      "env": {
        "META_ACCESS_TOKEN": "...",
        "META_APP_SECRET": "..."
      }
    }
  }
}

For local development against a clone of this repo:

{
  "mcpServers": {
    "meta": {
      "command": "node",
      "args": ["/absolute/path/to/meta-mcp-server/dist/index.js"],
      "env": {
        "META_ACCESS_TOKEN": "...",
        "META_APP_SECRET": "..."
      }
    }
  }
}

Token Provisioning (Cashtoken-specific)

The 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:

Business Settings → System Users → AI_Insights_Reader → Generate New Token
Pick the Hodusoft app (id 193481170220592)
In the scope picker, untick everything, then tick:
- 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
Copy the token (Meta only shows it once)
Paste over META_ACCESS_TOKEN in .env
Verify with meta_health_check and meta_token_inspect

Token TTL is ~60 days. Set a calendar reminder; rotation procedure documented in /governance/project-docs/runbook.md.

Repository layout

meta-mcp-server/
├── CLAUDE.md                          # AI agent rules (governance)
├── .cursorrules                       # Cursor agent rules
├── .github/
│   ├── copilot-instructions.md        # Copilot agent rules
│   ├── ISSUE_TEMPLATE/
│   └── workflows/                     # CI/CD (GitHub Actions, Sentinel status check)
├── .claude/skills/                    # 23 governance skills (scaffolding, review, git-ops, …)
├── .sentinelrc                        # Sentinel governance plugin config
├── CHANGELOG.md                       # SemVer release history
├── README.md
├── governance/                        # Governance assets — see /governance/standards/
│   ├── standards/                     # SDGP policies, coding standards
│   ├── templates/                     # Doc templates (specs, ADRs, deviations, project docs)
│   └── project-docs/                  # Project documents
│       ├── 1-vision-doc.md
│       ├── 2-brd.md
│       ├── 3-prd.md
│       ├── 5-tad.md
│       ├── runbook.md
│       ├── solution-doc-architecture.md
│       ├── specs/                     # Feature specs
│       ├── adr/                       # Architecture Decision Records
│       └── deviations/                # Governance deviation logs
├── src/                               # Implementation (see TAD)
│   ├── index.ts                       # stdio entrypoint
│   ├── server.ts                      # MCP server wiring
│   ├── config.ts                      # env + allowlists
│   ├── errors.ts                      # MetaError, ReadOnlyViolationError
│   ├── logger.ts                      # pino, stderr only, redacts secrets
│   ├── constants.ts
│   ├── context.ts
│   ├── helpers/
│   │   ├── graph-client.ts            # GET-only axios client + retry + cache + appsecret_proof
│   │   ├── cache.ts                   # LRU TTL cache
│   │   ├── format.ts                  # JSON / Markdown response formatting
│   │   └── schema.ts                  # Shared Zod shapes (pagination, date presets, IDs)
│   ├── tools/                         # 36 tool implementations grouped by domain
│   │   ├── token/  meta/  business/  ads/  pages/  instagram/  pixels/  catalog/  whatsapp/  overview/
│   │   ├── shared.ts                  # runList / runGet / errorResult helpers
│   │   └── register.ts                # Centralized tool registration
│   └── types/
└── tests/
    └── read-only-guard.mjs            # Runtime proof that POST/PUT/PATCH/DELETE are blocked

Governance

This project is initialized from the cashtokenrewards/project-governance-template and follows the Software Development Governance Policy (SDGP) in /governance/standards/sdgp-main.md.

Three absolute rules:

No feature is built without an approved spec. (/governance/project-docs/specs/)
No ADR is written without a parent feature spec. (/governance/project-docs/adr/)
No implementation begins without the spec and all required ADRs approved.

The current implementation (commit zero) was bootstrapped against an initial pass of governance docs:

| Doc | Path | |---|---| | Vision | governance/project-docs/1-vision-doc.md | | BRD | governance/project-docs/2-brd.md | | PRD | governance/project-docs/3-prd.md | | TAD | governance/project-docs/5-tad.md | | Runbook | governance/project-docs/runbook.md | | Specs | governance/project-docs/specs/ | | ADRs | governance/project-docs/adr/ | | Deviations | governance/project-docs/deviations/ |

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 §7.4.

AI agent rules: CLAUDE.md, .cursorrules, .github/copilot-instructions.md. Sentinel keeps these in sync with the central governance config.

Sentinel

This repository is tracked by the Sentinel governance plugin. Configuration lives at .sentinelrc. On any clone:

export SENTINEL_GITHUB_TOKEN="ghp_..."     # Personal access token with repo:read
sentinel sync                               # Pull latest org-level governance into CLAUDE.md

/sentinel-sync and /sentinel-status slash commands are also available inside Claude Code once the plugin is installed.

Scripts

| Script | What it does | |---|---| | npm run build | Clean + compile TypeScript → dist/ | | npm run dev | Run with tsx (no build step) | | npm run start | Run built dist/index.js | | npm run inspect | Build + open MCP Inspector | | npm run check:types | tsc --noEmit | | npm run test:readonly | Build + runtime proof that POST/PUT/PATCH/DELETE are blocked by the Graph client | | npm test | (placeholder for jest suite — see SPEC-07-eval-suite.md when added) |

Status

| Aspect | State | |---|---| | Implementation | v0.1.0 — bootstrapped, 36 tools, build clean, read-only guard verified | | Governance docs | Initial pass — Vision / BRD / PRD / TAD / Runbook / 3 ADRs / 1 deviation drafted | | App-level (Meta) | Hodusoft app in development tier for Marketing API. Standard Access via App Review pending. | | 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 | | 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 |

License

MIT — see LICENSE.