Skip to content
Back to search

meta-mcp

MCP Server for connecting to the Meta Marketing API

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today
Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/brijr--meta-mcp/badge.svg)](/listings/brijr--meta-mcp)

HTML

<a href="/listings/brijr--meta-mcp"><img src="/api/listings/brijr--meta-mcp/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

README.md · README · 314 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

  1. # Meta Ads MCP Server
  2. A Cloudflare Workers MCP server for Meta Ads account setup, campaign management, ad sets, creatives, audiences, reporting, and batch workflows.
  3. This repo is built on `xmcp` and exposes a Streamable HTTP MCP endpoint plus browser-facing Meta OAuth routes.
  4. ## Open Source / Self-Hosted
  5. This repository is intended to be deployed in your own Cloudflare account with your own Meta app credentials.
  6. It does not ship with:
  7. - a hosted control plane
  8. - a shared Meta app
  9. - a built-in end-user dashboard
  10. - a JWT issuer for your users and workspaces
  11. You bring:
  12. - your Cloudflare Worker deployment
  13. - your Meta developer app
  14. - your JWT issuer or auth provider
  15. - your own UI or backend that initiates the OAuth flow
  16. ## What It Does
  17. - Runs as a Cloudflare Worker
  18. - Uses direct Meta Graph API `fetch` calls instead of the Meta SDK
  19. - Stores Meta user connections per workspace in D1
  20. - Stores short-lived OAuth state in KV
  21. - Encrypts stored Meta access tokens
  22. - Protects MCP requests with your app-issued JWTs
  23. ## Endpoints
  24. - `GET /health`
  25. - `GET /app`
  26. - `POST /mcp`
  27. - `GET /oauth/meta/start`
  28. - `GET /oauth/meta/callback`
  29. ## Auth Model
  30. This server is multi-tenant. Every MCP request must include a bearer JWT issued by your app.
  31. If you are open-sourcing this project, the important implication is that consumers must wire it into their own auth system. The server does not know how to identify a user or workspace without that JWT.
  32. Required JWT claims:
  33. - `sub` or `userId`
  34. - `workspaceId`
  35. - optional `roles`
  36. Example payload:
  37. ```json
  38. {
  39. "sub": "user_123",
  40. "workspaceId": "workspace_abc",
  41. "roles": ["admin"]
  42. }
  43. ```
  44. Why `/oauth/meta/start` is not a generic public link:
  45. - the server must know which workspace the Meta account should be attached to
  46. - that workspace context comes from the JWT
  47. - without it, the server cannot safely bind the resulting Meta token
  48. ## Tool Surface
  49. Implemented tool families:
  50. - Account and setup
  51. - Campaign management
  52. - Ad set management
  53. - Creative and ads
  54. - Audience and targeting
  55. - Reporting and insights
  56. - Batch helpers
  57. The server currently registers 39 tools.
  58. ## Project Layout
  59. - `src/tools` tool definitions grouped by domain
  60. - `src/lib` auth, storage, OAuth, runtime, and Meta client helpers
  61. - `src/services` domain-specific Meta service logic
  62. - `src/middleware.ts` OAuth routing and MCP JWT auth
  63. - `cloudflare-entry.mjs` Worker wrapper entry for Cloudflare-specific route interception
  64. - `schema.sql` D1 schema
  65. - `test` unit and contract-style tests
  66. ## Local Development
  67. Install dependencies:
  68. ```bash
  69. pnpm install
  70. ```
  71. Run local dev:
  72. ```bash
  73. pnpm dev
  74. ```
  75. Useful scripts:
  76. ```bash
  77. pnpm build
  78. pnpm test
  79. pnpm deploy
  80. ```
  81. ## Cloudflare Bindings
  82. Required bindings:
  83. - D1 database bound as `META_DB`
  84. - KV namespace bound as `META_OAUTH_STATE`
  85. Required secrets:
  86. - `JWT_SECRET` or `JWT_JWKS_URL`
  87. - `META_APP_ID`
  88. - `META_APP_SECRET`
  89. - `META_TOKEN_ENCRYPTION_KEY`
  90. - `APP_UI_PASSWORD` for the built-in admin page at `/app`
  91. Optional configuration:
  92. - `JWT_ISSUER`
  93. - `JWT_AUDIENCE`
  94. - `APP_SESSION_SECRET`
  95. - `APP_UI_WORKSPACE_ID`
  96. - `APP_UI_USER_ID`
  97. - `META_REDIRECT_URI`
  98. - `META_GRAPH_VERSION`
  99. - `META_OAUTH_SCOPES`
  100. - `META_OAUTH_ALLOWED_RETURN_ORIGINS`
  101. Defaults:
  102. - `META_GRAPH_VERSION=v25.0`
  103. - `META_OAUTH_SCOPES=ads_management,business_management`
  104. - `APP_UI_WORKSPACE_ID=workspace_admin`
  105. - `APP_UI_USER_ID=app_admin`
  106. ## Built-In Admin UI
  107. The Worker now includes a small browser UI at `/app`.
  108. What it does:
  109. - prompts for an admin password
  110. - starts the existing Meta OAuth flow without requiring you to manually mint a bearer JWT
  111. - shows whether a Meta account is connected for the admin workspace
  112. - loads accessible ad accounts using the same service logic as `get_ad_accounts`
  113. Required setup:
  114. 1. Set `APP_UI_PASSWORD` on the Worker.
  115. 2. Make sure `META_REDIRECT_URI` matches your public host, for example:
  116. ```text
  117. https://meta-mcp.gestalt.xyz/oauth/meta/callback
  118. ```
  119. 3. Open:
  120. ```text
  121. https://meta-mcp.gestalt.xyz/app
  122. ```
  123. ## Meta App Setup
  124. In your Meta app:
  125. 1. Add the Marketing API product.
  126. 2. Add a Website platform.
  127. 3. Set the Website platform URL to your Worker origin.
  128. 4. Set `App Domains` to your Worker domain.
  129. 5. Set the callback URL to:
  130. ```text
  131. https://<your-worker-host>/oauth/meta/callback
  132. ```
  133. If your app uses `Facebook Login` or `Facebook Login for Business`, also add that exact callback URL to the product-specific redirect URI settings.
  134. For a Worker deployed on `workers.dev`, these fields usually need to match the Worker host exactly.
  135. ## Database
  136. Apply the D1 schema:
  137. ```bash
  138. pnpm wrangler d1 execute META_DB --remote --file schema.sql -y
  139. ```
  140. Tables:
  141. - `meta_connections`
  142. - `meta_ad_accounts_cache`
  143. ## Deployment
  144. Deploy the Worker:
  145. ```bash
  146. pnpm deploy
  147. ```
  148. After deploy:
  149. 1. note the public Worker URL
  150. 2. set `META_REDIRECT_URI` to `https://<your-worker-host>/oauth/meta/callback`
  151. 3. update the same callback in the Meta app settings
  152. If you plan to use a separate frontend or dashboard on another origin, allow that origin for post-OAuth browser redirects:
  153. ```text
  154. META_OAUTH_ALLOWED_RETURN_ORIGINS=https://your-ui.example.com,http://localhost:3000
  155. ```
  156. Use your real frontend origin in production.
  157. ## Manual Test Flow
  158. ### 1. Generate a short-lived JWT
  159. Use the same JWT secret your app uses for the Worker.
  160. ```bash
  161. export JWT_SECRET="YOUR_JWT_SECRET"
  162. TOKEN=$(node --input-type=module <<'NODE'
  163. import { SignJWT } from 'jose';
  164. const secret = new TextEncoder().encode(process.env.JWT_SECRET);
  165. const token = await new SignJWT({ workspaceId: 'workspace_test', roles: ['admin'] })
  166. .setProtectedHeader({ alg: 'HS256' })
  167. .setSubject('user_test')
  168. .setIssuedAt()
  169. .setExpirationTime('10m')
  170. .sign(secret);
  171. console.log(token);
  172. NODE
  173. )
  174. ```
  175. ### 2. Start Meta OAuth
  176. ```bash
  177. curl -i \
  178. -H "Authorization: Bearer $TOKEN" \
  179. "https://<your-worker-host>/oauth/meta/start?workspace_id=workspace_test"
  180. ```
  181. Copy the `Location` header into your browser and complete the Meta login flow.
  182. Expected success page:
  183. ```text
  184. Meta account connected.
  185. ```
  186. ### 3. Initialize MCP
  187. ```bash
  188. curl -s https://<your-worker-host>/mcp \
  189. -H "Authorization: Bearer $TOKEN" \
  190. -H "Content-Type: application/json" \
  191. -H "Accept: application/json" \
  192. -d '{"jsonrpc":"2.0","id":"init-1","method":"initialize","params":{"protocolVersion":"2025-03-26","capabilities":{},"clientInfo":{"name":"manual-test","version":"1.0.0"}}}'
  193. ```
  194. ### 4. List Tools
  195. ```bash
  196. curl -s https://<your-worker-host>/mcp \
  197. -H "Authorization: Bearer $TOKEN" \
  198. -H "Content-Type: application/json" \
  199. -H "Accept: application/json" \
  200. -d '{"jsonrpc":"2.0","id":"tools-1","method":"tools/list","params":{}}'
  201. ```
  202. ### 5. Call a Real Tool
  203. After OAuth succeeds, this should return the accessible ad accounts for that workspace:
  204. ```bash
  205. curl -s https://<your-worker-host>/mcp \
  206. -H "Authorization: Bearer $TOKEN" \
  207. -H "Content-Type: application/json" \
  208. -H "Accept: application/json" \
  209. -d '{"jsonrpc":"2.0","id":"call-1","method":"tools/call","params":{"name":"get_ad_accounts","arguments":{}}}'
  210. ```
  211. If you get a connect/reconnect error, the OAuth flow and the MCP call used different `workspaceId` values.
  212. ## Notes
  213. - Cloudflare `workers.dev` domains can require extra care in Meta app settings.
  214. - The Worker entrypoint explicitly intercepts OAuth routes before delegating to the generated XMCP Worker.
  215. - The Cloudflare Worker build path is not identical to local `xmcp dev`, so always verify the deployed routes after OAuth-related changes.
  216. ## References
  217. - [XMCP](https://xmcp.dev/docs)
  218. - [Cloudflare Workers](https://developers.cloudflare.com/workers/)
  219. - [Meta Marketing API Authorization](https://developers.facebook.com/docs/marketing-api/overview/authorization/)

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.