{"_id":"@edvintoome/meta-mcp","_rev":"2-64f27c783fd22e1213ebb46fd4f5b9f3","name":"@edvintoome/meta-mcp","dist-tags":{"latest":"1.7.2"},"versions":{"1.7.1":{"name":"@edvintoome/meta-mcp","version":"1.7.1","keywords":["mcp","model-context-protocol","meta","facebook","instagram","advertising","marketing-api"],"author":{"name":"Edvin Toome"},"license":"MIT","_id":"@edvintoome/meta-mcp@1.7.1","maintainers":[{"name":"edvintoome","email":"edvin.toome@gmail.com"}],"homepage":"https://github.com/EdvinToome/meta-mcp#readme","bugs":{"url":"https://github.com/EdvinToome/meta-mcp/issues"},"bin":{"meta-mcp":"build/index.js"},"dist":{"shasum":"000a7359cdd5826f800a96715d4f8a07947ec990","tarball":"https://registry.npmjs.org/@edvintoome/meta-mcp/-/meta-mcp-1.7.1.tgz","fileCount":7,"integrity":"sha512-HmbrqzEYvpK8BM3TksTpLy9xjgPF+JdSKV3U7B6iXS+ULdBPGjm0c5Cv1yNla7/1dT+3UBTiPtojhPcjQbpoNA==","signatures":[{"sig":"MEUCIBSqnIFK45tdXdZqitXTwq0fmjdJYOuEGGo9aFboZtmlAiEAl5DWhNIAHqkx+1hr7Y4WkV6V3JexT2SmccY37wT41ro=","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":881316},"main":"build/index.js","type":"module","engines":{"node":">=18.0.0"},"gitHead":"e5cc53214d47c81048a7043bdbf458a5809e24f0","scripts":{"dev":"tsx src/index.ts","lint":"eslint src/**/*.ts","test":"jest","build":"tsup","check":"node scripts/health-check.js","setup":"node scripts/setup-mcp.js","prepare":"npm run build","test:api":"tsx test-api.js","setup:mcp":"node scripts/setup-mcp.js","dev:vercel":"vercel dev","list:tools":"tsx list-tools.js","test:tools":"tsx test-tools.js","health-check":"node scripts/health-check.js","vercel-build":"npm run build"},"_npmUser":{"name":"edvintoome","email":"edvin.toome@gmail.com"},"repository":{"url":"git+https://github.com/EdvinToome/meta-mcp.git","type":"git"},"_npmVersion":"10.8.2","description":"Model Context Protocol server for Meta Marketing API integration","directories":{},"_nodeVersion":"20.19.5","dependencies":{"zod":"^3.25.76","jose":"^6.1.3","redis":"^5.10.0","dotenv":"^17.2.3","@vercel/kv":"^3.0.0","node-fetch":"^3.3.2","@vercel/mcp-adapter":"^0.11.2","@modelcontextprotocol/sdk":"^1.25.2"},"publishConfig":{"access":"public"},"_hasShrinkwrap":false,"devDependencies":{"tsx":"^4.21.0","jest":"^29.7.0","tsup":"^8.5.0","eslint":"^9.39.2","ts-jest":"^29.4.6","typescript":"^5.9.3","@types/jest":"^29.5.14","@types/node":"^20.19.28","@faker-js/faker":"^9.9.0","@typescript-eslint/parser":"^8.52.0","@typescript-eslint/eslint-plugin":"^8.52.0"},"_npmOperationalInternal":{"tmp":"tmp/meta-mcp_1.7.1_1773867735607_0.11825275976023053","host":"s3://npm-registry-packages-npm-production"}},"1.7.2":{"name":"@edvintoome/meta-mcp","version":"1.7.2","description":"Model Context Protocol server for Meta Marketing API integration","main":"build/index.js","type":"module","bin":{"meta-mcp":"scripts/cli.js"},"scripts":{"build":"tsup","dev":"tsx src/index.ts","dev:vercel":"vercel dev","test":"jest","test:tools":"tsx test-tools.js","list:tools":"tsx list-tools.js","test:api":"tsx test-api.js","lint":"eslint src/**/*.ts","prepare":"npm run build","prepack":"npm run build","vercel-build":"npm run build","setup":"node scripts/setup-mcp.js","setup:mcp":"node scripts/setup-mcp.js","setup:codex":"node scripts/setup-codex.js","setup:codex-plugin":"node scripts/setup-codex-plugin.js","setup:claude":"node scripts/setup-claude.js","init:workspace":"node scripts/init-workspace-config.js","health-check":"node scripts/health-check.js","check":"node scripts/health-check.js","structured-build":"tsx scripts/run-structured-build.ts"},"author":{"name":"Edvin Toome"},"license":"MIT","publishConfig":{"access":"public"},"repository":{"type":"git","url":"git+https://github.com/EdvinToome/meta-mcp.git"},"homepage":"https://github.com/EdvinToome/meta-mcp#readme","bugs":{"url":"https://github.com/EdvinToome/meta-mcp/issues"},"keywords":["mcp","model-context-protocol","meta","facebook","instagram","advertising","marketing-api"],"dependencies":{"@modelcontextprotocol/sdk":"^1.25.2","@vercel/kv":"^3.0.0","@vercel/mcp-adapter":"^0.11.2","dotenv":"^17.2.3","jose":"^6.1.3","node-fetch":"^3.3.2","openai":"^6.33.0","redis":"^5.10.0","sharp":"^0.34.4","zod":"^3.25.76"},"devDependencies":{"@faker-js/faker":"^9.9.0","@types/jest":"^29.5.14","@types/node":"^20.19.28","@typescript-eslint/eslint-plugin":"^8.52.0","@typescript-eslint/parser":"^8.52.0","eslint":"^9.39.2","jest":"^29.7.0","ts-jest":"^29.4.6","tsup":"^8.5.0","tsx":"^4.21.0","typescript":"^5.9.3"},"engines":{"node":">=18.0.0"},"gitHead":"d408e6510827e3e7d0dba67b468d1de0620f05d8","_id":"@edvintoome/meta-mcp@1.7.2","_nodeVersion":"24.14.1","_npmVersion":"11.11.0","dist":{"integrity":"sha512-DBLb3TtavmQqRVeyIQMZlFvYoSs4TwfLwUvezaVyvzTQsoZXSZxudvDLt1TOERd36gdeF55ud9XRG610qHJ3lw==","shasum":"3a7ed0f3a972a7446ffdc776b00a7fdc09e4dd39","tarball":"https://registry.npmjs.org/@edvintoome/meta-mcp/-/meta-mcp-1.7.2.tgz","fileCount":51,"unpackedSize":1089761,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEQCIBNnYrAYD5+6Siv5ewFYvKuCk8VJ/RzLWI6Wl4JakRcHAiBZW4BjyFBegRpbVtZ5b/mQZfm5gxCiZwZd/zmVgf2gQQ=="}]},"_npmUser":{"name":"edvintoome","email":"edvin.toome@gmail.com"},"directories":{},"maintainers":[{"name":"edvintoome","email":"edvin.toome@gmail.com"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/meta-mcp_1.7.2_1775226507795_0.32829377534040116"},"_hasShrinkwrap":false}},"time":{"created":"2026-03-18T21:02:15.482Z","modified":"2026-04-03T14:28:28.131Z","1.7.1":"2026-03-18T21:02:15.756Z","1.7.2":"2026-04-03T14:28:28.018Z"},"bugs":{"url":"https://github.com/EdvinToome/meta-mcp/issues"},"author":{"name":"Edvin Toome"},"license":"MIT","homepage":"https://github.com/EdvinToome/meta-mcp#readme","keywords":["mcp","model-context-protocol","meta","facebook","instagram","advertising","marketing-api"],"repository":{"type":"git","url":"git+https://github.com/EdvinToome/meta-mcp.git"},"description":"Model Context Protocol server for Meta Marketing API integration","maintainers":[{"name":"edvintoome","email":"edvin.toome@gmail.com"}],"readme":"# Meta Marketing API MCP Server\n\nA Meta Ads MCP server plus agent bundle for Codex and Claude Code. The package provides the Meta API server, skill prompts, Claude slash commands, and local workspace initialization for site profiles and business-specific rules.\n\n## ⚡ Quick Start\n\n### 1) Install\n```bash\nnpm install -g @edvintoome/meta-mcp\n```\n\n### 2) Configure (Claude Desktop / Cursor)\nCreate or edit your MCP config:\n- **macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json`\n- **Windows**: `%APPDATA%\\Claude\\claude_desktop_config.json`\n- **Linux**: `~/.config/Claude/claude_desktop_config.json`\n\nMinimal config:\n```json\n{\n  \"mcpServers\": {\n    \"meta-ads\": {\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"@edvintoome/meta-mcp\"],\n      \"env\": {\n        \"META_ACCESS_TOKEN\": \"your_access_token_here\"\n      }\n    }\n  }\n}\n```\n\nIf your app requires `appsecret_proof`, add `META_APP_SECRET`:\n```json\n{\n  \"mcpServers\": {\n    \"meta-ads\": {\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"@edvintoome/meta-mcp\"],\n      \"env\": {\n        \"META_ACCESS_TOKEN\": \"your_access_token_here\",\n        \"META_APP_SECRET\": \"your_app_secret\"\n      }\n    }\n  }\n}\n```\n\n### 3) Restart your client\n- **Claude Desktop**: quit and reopen\n- **Cursor**: restart the IDE\n\n### 4) Verify\nRestart your MCP client, then call the `health_check` tool from the client.\n\n## Agent Bundle\n\nThis repo now ships as a Meta Ads agent bundle around the local `meta` MCP server.\n\nBundled skills:\n- `meta-ads-builder`\n- `meta-ads-consultant`\n- `meta-ads-morning-review`\n- `meta-ad-copy`\n- supporting `ad-creative`\n- supporting `paid-ads`\n\nTracked starter files:\n- [site-profiles.example.json](./site-profiles.example.json)\n- [BUSINESS_RULES.example.md](./BUSINESS_RULES.example.md)\n\nLocal runtime files:\n- `site-profiles.local.json`\n- `BUSINESS_RULES.local.md`\n\nCreate the local runtime files with:\n\n```bash\nnpm run init:workspace\n```\n\n## Codex Plugin\n\nCodex plugin discovery now uses the standard repo-local layout:\n- plugin bundle: `plugins/meta-mcp`\n- workspace marketplace: `.agents/plugins/marketplace.json`\n\nOpen this repo in Codex and the plugin can be discovered from the local workspace marketplace.\n\nIf you want it available outside this repo too, run:\n\n```bash\nnpm run setup:codex-plugin\n```\n\nThat installer:\n- creates `~/plugins/meta-mcp` as a link to this repo\n- writes `~/.agents/plugins/marketplace.json`\n- enables `meta-mcp@meta-mcp-local` in `~/.codex/config.toml`\n\nIf you are using the published package instead of a clone, you can also install it with:\n\n```bash\nnpx -y @edvintoome/meta-mcp install-codex-plugin\n```\n\n## Codex + Meta Skills\n\nThis repo ships repo-local skills under `skills/`.\n\nUse `npm run setup:codex` to wire both pieces together:\n- installs all repo Meta skills into `~/.codex/skills`\n- updates `~/.codex/config.toml` with a local `meta` MCP server pointing at `src/index.ts`\n- reuses the `meta` namespace the skills expect, so `mcp__meta__...` calls resolve without extra mapping\n\nWhy this split works:\n- the skills are the orchestration layer\n- the MCP server is the execution layer that talks to Meta\n- keeping the skills symlinked to the repo means skill updates ship with the repo and do not need manual copying\n\nAfter setup, restart Codex and use prompts like:\n\n```text\nUse $meta-ads-builder to publish a paused Meta ad from /absolute/path/to/image.jpg for the selected site profile\n```\n\nThe builder skill will:\n- call `health_check` and `get_capabilities`\n- resolve the matching site profile from `site-profiles.local.json`\n- use the selected image or enumerate image candidates from your working folder\n- persist `meta-ads-brief.json` and `meta-ads-result.json` in the working folder\n\nThe consultant and morning-review skills use the same MCP server and site profiles for diagnosis, daily reporting, creative feedback, and optimization advice.\n\n## 🚀 Features\n\n### **Campaign Management**\n- ✅ Create, update, pause, resume, and delete campaigns\n- ✅ Support for all campaign objectives (traffic, conversions, awareness, etc.)\n- ✅ Budget management and scheduling\n- ✅ Ad set creation with advanced targeting\n- ✅ Individual ad management\n\n### **Analytics & Reporting**\n- 📊 Performance insights with customizable date ranges\n- 📈 Multi-object performance comparison\n- 📋 Data export in CSV/JSON formats\n- 🎯 Attribution modeling and conversion tracking\n- 📅 Daily performance trends analysis\n\n### **Audience Management**\n- 👥 Custom audience creation and management\n- 🎯 Lookalike audience generation\n- 📏 Audience size estimation\n- 🔍 Targeting recommendations and insights\n- 🏥 Audience health monitoring\n\n### **Creative Management**\n- 🎨 Ad creative creation and management\n- 👁️ Cross-platform ad previews\n- 🧪 A/B testing setup and guidance\n- 📸 Creative performance analysis\n\n### **Enterprise Features**\n- 🔐 Secure OAuth 2.0 authentication\n- ⚡ Automatic rate limiting with exponential backoff\n- 🔄 Pagination support for large datasets\n- 🛡️ Comprehensive error handling\n- 📚 Rich MCP resources for contextual data access\n- 🌐 Multi-account support\n\n## 📦 Installation & Setup\n\n### Option 1: Direct Installation (Recommended)\n```bash\nnpm install -g @edvintoome/meta-mcp\n```\n\n### Option 2: From Source\n```bash\ngit clone https://github.com/EdvinToome/meta-mcp.git\ncd meta-mcp\nnpm install\nnpm run build\n```\n\n### Option 3: Automated Setup (Easiest)\n```bash\n# Clone the repository first\ngit clone https://github.com/EdvinToome/meta-mcp.git\ncd meta-mcp\n\n# Run the interactive setup\nnpm run setup\n```\n\nThe setup script will:\n- ✅ Check system requirements\n- ✅ Validate your Meta access token\n- ✅ Create Claude Desktop configuration\n- ✅ Install dependencies\n- ✅ Test the connection\n\n### Codex Setup\n\nIf you want Codex to use this MCP server together with the bundled Meta skills:\n\n```bash\nnpm install\nnpm run setup:codex\n```\n\nThe installer uses a local source setup:\n- MCP server command: `node_modules/.bin/tsx src/index.ts`\n- Codex MCP server name: `meta`\n- skill install target: `~/.codex/skills/*`\n\nIf you already have different skills at those targets, re-run with `--force` to replace them:\n\n```bash\nnpm run setup:codex -- --force\n```\n\n### Claude Code Setup\n\nClaude Code can use the same repo directly:\n\n- `.mcp.json` exposes the local `meta` MCP server\n- `CLAUDE.md` provides project instructions\n- `.claude/commands/` provides ready-to-use slash commands\n- the local server still expects `META_ACCESS_TOKEN` and optional `META_APP_*` variables in the shell that launches Claude Code\n- local business data should live in `site-profiles.local.json` and `BUSINESS_RULES.local.md`\n\nExample commands after opening the repo in Claude Code:\n- `/meta-ads-builder`\n- `/meta-ads-consultant`\n- `/meta-ads-morning-review`\n- `/meta-ad-copy`\n\nTo install the Meta bundle into another Claude Code project:\n\n```bash\nnpm run setup:claude -- --project /absolute/path/to/project\n```\n\nThat installer:\n- merges a local `meta` server into the target project's `.mcp.json`\n- installs Meta slash commands under `.claude/commands`\n- links the Meta skills and profile docs under `.claude/meta-mcp`\n- creates editable `.claude/meta-mcp/site-profiles.local.json` and `.claude/meta-mcp/BUSINESS_RULES.local.md` if they do not exist\n- appends a small managed Meta section to the target `CLAUDE.md`\n\nIf you are using the published package instead of a clone:\n\n```bash\nnpx -y @edvintoome/meta-mcp install-claude --project /absolute/path/to/project\n```\n\nAfter installation:\n1. Edit `.claude/meta-mcp/site-profiles.local.json`\n2. Edit `.claude/meta-mcp/BUSINESS_RULES.local.md`\n3. Make sure the shell that launches Claude Code has `META_ACCESS_TOKEN`\n4. Open the project in Claude Code and run `/meta-ads-builder`\n\n## 🔧 Configuration Guide\n\n### Step 1: Get Meta Access Token\n1. Create a Meta App at [developers.facebook.com](https://developers.facebook.com/)\n2. Add Marketing API product\n3. Generate an access token with `ads_read` and `ads_management` permissions\n4. If your app requires `appsecret_proof`, set `META_APP_SECRET` (see below)\n5. (Optional) Set up OAuth for automatic token refresh\n\n![CleanShot 2025-06-17 at 15 52 35@2x](https://github.com/user-attachments/assets/160a260f-8f1b-44de-9041-f684a47e4a9d)\n\n### Step 2: Configure Claude Desktop\n\n#### Find your configuration file:\n- **macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json`\n- **Windows**: `%APPDATA%\\Claude\\claude_desktop_config.json`\n- **Linux**: `~/.config/Claude/claude_desktop_config.json`\n\nIf the file doesn't exist, create it with the following content:\n\n#### Basic Configuration (Token-based):\n```json\n{\n  \"mcpServers\": {\n    \"meta-ads\": {\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"@edvintoome/meta-mcp\"],\n      \"env\": {\n        \"META_ACCESS_TOKEN\": \"your_access_token_here\"\n      }\n    }\n  }\n}\n```\n\n#### Advanced Configuration (with OAuth + appsecret_proof):\n```json\n{\n  \"mcpServers\": {\n    \"meta-ads\": {\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"@edvintoome/meta-mcp\"],\n      \"env\": {\n        \"META_ACCESS_TOKEN\": \"your_access_token_here\",\n        \"META_APP_ID\": \"your_app_id\",\n        \"META_APP_SECRET\": \"your_app_secret\",\n        \"META_AUTO_REFRESH\": \"true\",\n        \"META_BUSINESS_ID\": \"your_business_id\"\n      }\n    }\n  }\n}\n```\n\n#### Local Development Configuration:\nIf you've cloned the repository locally:\n```json\n{\n  \"mcpServers\": {\n    \"meta-ads\": {\n      \"command\": \"node\",\n      \"args\": [\"/absolute/path/to/meta-mcp/build/index.js\"],\n      \"env\": {\n        \"META_ACCESS_TOKEN\": \"your_access_token_here\"\n      }\n    }\n  }\n}\n```\n\n#### Codex Local Configuration:\n\nUse the bundled example in [examples/codex_config.toml](./examples/codex_config.toml) or add this to `~/.codex/config.toml`:\n\n```toml\n[mcp_servers.meta]\ncommand = \"/absolute/path/to/meta-mcp/node_modules/.bin/tsx\"\nargs = [\"/absolute/path/to/meta-mcp/src/index.ts\"]\nenabled = true\n\n[mcp_servers.meta.env]\nMETA_ACCESS_TOKEN = \"your_meta_access_token_here\"\nMETA_APP_ID = \"your_app_id_optional\"\nMETA_APP_SECRET = \"your_app_secret_optional\"\nMETA_BUSINESS_ID = \"your_business_id_optional\"\nMETA_AUTO_REFRESH = \"true\"\n```\n\nThe server name should stay `meta` if you want the bundled skill to work without edits, because the skill calls `mcp__meta__...` tools directly.\n\n### Step 3: Configure for Cursor\n\nCursor uses the same MCP configuration as Claude Desktop. Add the configuration to your Cursor settings:\n\n1. Open Cursor Settings\n2. Go to \"Extensions\" > \"Claude\"\n3. Add the MCP server configuration in the JSON settings\n\n### Step 4: Restart Your Client\n- **Claude Desktop**: Completely quit and restart the application\n- **Cursor**: Restart the IDE\n\n### Step 5: Verify Setup\n```bash\n# Verify from your MCP client by calling the health_check tool\n```\n\n## 🔍 Troubleshooting\n\n### Common Issues\n\n#### 1. \"Command not found\" or \"npx\" errors\n```bash\n# Install Node.js if not installed\n# macOS: brew install node\n# Windows: Download from nodejs.org\n# Linux: Use your package manager\n\n# Verify installation\nnode --version\nnpm --version\nnpx --version\n```\n\n#### 2. Permission errors\n```bash\n# Fix npm permissions (macOS/Linux)\nsudo chown -R $(whoami) $(npm config get prefix)/{lib/node_modules,bin,share}\n\n# Or install without sudo\nnpm config set prefix ~/.npm-global\necho 'export PATH=~/.npm-global/bin:$PATH' >> ~/.bashrc\nsource ~/.bashrc\n```\n\n#### 3. Meta API connection issues\n```bash\n# Test your token manually\ncurl -G \\\n  -d \"access_token=YOUR_ACCESS_TOKEN\" \\\n  \"https://graph.facebook.com/v23.0/me/adaccounts\"\n```\nIf the response says `appsecret_proof` is required, set `META_APP_SECRET` in your MCP server environment.\n\n#### 4. Check Claude Desktop logs\n- **macOS**: `~/Library/Logs/Claude/mcp*.log`\n- **Windows**: `%APPDATA%\\Claude\\logs\\mcp*.log`\n\n```bash\n# macOS/Linux - View logs\ntail -f ~/Library/Logs/Claude/mcp*.log\n\n# Windows - View logs\ntype \"%APPDATA%\\Claude\\logs\\mcp*.log\"\n```\n\n#### 5. Test the server manually\n```bash\n# Test the MCP server directly\nnpx -y @edvintoome/meta-mcp\n\n# Or if installed locally\nnode build/index.js\n```\n\n### Debug Mode\nEnable debug logging by adding to your environment:\n```json\n{\n  \"mcpServers\": {\n    \"meta-ads\": {\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"@edvintoome/meta-mcp\"],\n      \"env\": {\n        \"META_ACCESS_TOKEN\": \"your_access_token_here\",\n        \"META_MCP_DEBUG\": \"1\",\n        \"NODE_ENV\": \"development\"\n      }\n    }\n  }\n}\n```\n\n## 🌐 Web Deployment (Vercel)\n\nFor web applications, you can deploy this server to Vercel and expose an HTTP MCP endpoint:\n\n### Configuration:\n1. Deploy to Vercel\n2. Set environment variables in Vercel dashboard\n3. Configure OAuth app in Meta Developer Console\n4. Use the web endpoint: `https://your-project.vercel.app/api/mcp`\n\n### MCP Client Configuration for Web:\n```json\n{\n  \"mcpServers\": {\n    \"meta-ads-remote\": {\n      \"url\": \"https://your-project.vercel.app/api/mcp\",\n      \"headers\": {\n        \"Authorization\": \"Bearer your_session_token\"\n      }\n    }\n  }\n}\n```\n\n**Note**: You need to authenticate against your deployment to get a session token.\n\n### Remote MCP Configuration (mcp-remote)\nFor Vercel deployments, use `mcp-remote` to bridge HTTP to stdio:\n```json\n{\n  \"mcpServers\": {\n    \"meta-ads\": {\n      \"command\": \"npx\",\n      \"args\": [\n        \"-y\",\n        \"mcp-remote\",\n        \"https://your-project.vercel.app/api/mcp\",\n        \"--header\",\n        \"Authorization:${META_AUTH_HEADER}\"\n      ],\n      \"env\": {\n        \"META_AUTH_HEADER\": \"Bearer your_session_token_here\"\n      }\n    }\n  }\n}\n```\n\n## 🛠️ Available Tools\n\nThis MCP server provides **25 comprehensive tools** across all major Meta advertising categories:\n\n### 📊 Analytics & Insights (3 tools)\n- **`get_insights`** - Get detailed performance metrics (impressions, clicks, ROAS, CTR, CPC, etc.)\n- **`compare_performance`** - Side-by-side performance comparison of multiple campaigns/ads\n- **`export_insights`** - Export performance data in JSON or CSV formats\n\n### 📈 Campaign Management (4 tools)\n- **`create_campaign`** - Create new advertising campaigns with full configuration (includes special_ad_categories)\n- **`update_campaign`** - Modify existing campaigns (name, budget, status, etc.)\n- **`pause_campaign`** - Pause active campaigns\n- **`resume_campaign`** - Resume/activate paused campaigns\n\n### 🎯 Ad Set Management (2 tools)\n- **`create_ad_set`** - Create ad sets with detailed targeting, budgets, and optimization goals\n- **`list_ad_sets`** - List and filter ad sets within campaigns\n\n### 📱 Ad Management (2 tools)\n- **`create_ad`** - Create individual ads within ad sets using creative IDs\n- **`list_ads`** - List and filter ads by ad set, campaign, or account\n\n### 👥 Audience Management (4 tools)\n- **`list_audiences`** - List all custom audiences for an account\n- **`create_custom_audience`** - Create custom audiences from various sources\n- **`create_lookalike_audience`** - Generate lookalike audiences from source audiences\n- **`get_audience_info`** - Get detailed information about specific audiences\n\n### 🎨 Creative Management (2 tools)\n- **`list_ad_creatives`** - List all ad creatives for an account\n- **`create_ad_creative`** - Create new ad creatives with rich specifications (supports external image URLs)\n\n### 🔧 Account & Basic Tools (3 tools)\n- **`health_check`** - Comprehensive authentication and server status check\n- **`get_ad_accounts`** - List accessible Meta ad accounts\n- **`get_campaigns`** - List campaigns with filtering options\n\n### 🔐 Authentication Tools (1 tool)\n- **`get_token_info`** - Token validation and information retrieval\n\n### 🩺 Diagnostic Tools (2 tools)\n- **`diagnose_campaign_readiness`** - Check campaign status and identify ad set creation issues\n- **`check_account_setup`** - Comprehensive account validation and setup verification\n\n## 🛠️ Usage Examples\n\n### Test the Connection\n```\nCheck the health of the Meta Marketing API server and authentication status\n```\n\n### Analytics & Performance Insights  \n```\nGet detailed performance insights for my Deal Draft campaign including impressions, clicks, ROAS, and CTR for the last 30 days\n```\n```\nCompare the performance of my top 3 campaigns side-by-side for the last quarter\n```\n```\nExport campaign performance data for all my campaigns last month in CSV format\n```\n\n### Campaign Management\n```\nCreate a new traffic campaign named \"Holiday Sale 2024\" with a $50 daily budget and OUTCOME_TRAFFIC objective\n```\n```\nUpdate my existing campaign budget to $100 daily and change the name to \"Black Friday Special\"\n```\n```\nPause all campaigns that have a CPC above $2.00\n```\n```\nResume my paused \"Summer Collection\" campaign\n```\n\n### Complete Campaign Setup (Campaign → Ad Set → Ads)\n```\nCreate a complete \"Test 3\" campaign setup: 1) Create the campaign with OUTCOME_LEADS objective, 2) Create an ad set targeting US users aged 25-45 interested in entrepreneurship, 3) Create 4 different ads using my existing creatives\n```\n```\nCreate an ad set for my existing campaign targeting women aged 30-50 in major US cities with interests in business and personal development\n```\n```\nCreate a new ad in my ad set using creative ID 123456 and name it \"Headline Test A\"\n```\n\n### Troubleshooting & Diagnostics\n```\nDiagnose my \"Test 3\" campaign to see if it's ready for ad set creation and identify any potential issues\n```\n```\nCheck my account setup to verify payment methods, business verification, and ad account permissions\n```\n```\nCheck why my ad set creation failed and get specific recommendations for my account setup\n```\n\n### Audience Management\n```\nList all my custom audiences and show their sizes and status\n```\n```\nCreate a custom audience named \"Website Visitors\" from people who visited my site\n```\n```\nCreate a 5% lookalike audience based on my \"High Value Customers\" audience targeting the US\n```\n```\nGet detailed information about my \"Newsletter Subscribers\" audience including health status\n```\n\n### Creative Management\n```\nList all my ad creatives and show their performance data\n```\n```\nCreate a new ad creative for my holiday campaign with external image URL from my website and specific messaging\n```\n\n### Account Management\n```\nShow me all my accessible Meta ad accounts with their currencies and time zones\n```\n```\nGet my current access token information including permissions and expiration\n```\n\n## 📚 Resources Access\n\nThe server provides rich contextual data through MCP resources:\n\n- `meta://campaigns/{account_id}` - Campaign overview\n- `meta://insights/account/{account_id}` - Performance dashboard\n- `meta://audiences/{account_id}` - Audience insights\n- `meta://audience-health/{account_id}` - Audience health report\n\n## 🔧 Environment Variables\n\n### Required\n```bash\nMETA_ACCESS_TOKEN=your_access_token_here\n```\n\n### Optional\n```bash\nMETA_APP_ID=your_app_id                    # For OAuth\nMETA_APP_SECRET=your_app_secret            # For OAuth\nMETA_BUSINESS_ID=your_business_id          # For business-specific operations\nMETA_API_VERSION=v23.0                     # API version (default: v23.0)\nMETA_API_TIER=standard                     # 'development' or 'standard'\nMETA_AUTO_REFRESH=true                     # Enable automatic token refresh\nMETA_REFRESH_TOKEN=your_refresh_token      # For token refresh\nMETA_MCP_REQUEST_TIMEOUT_MS=30000          # Request timeout in ms (0 to disable)\nMETA_MCP_DEBUG=1                           # Enable verbose MetaApiClient debug logs\n```\n\n## 📖 Documentation\n\n- **All documentation is in this README** (setup, configuration, and tools)\n- **[Example Configuration](examples/claude_desktop_config.json)** - Sample configuration file\n\n## 🏗️ Architecture\n\n```\n┌─────────────────┐    ┌──────────────────┐    ┌─────────────────┐\n│   Claude AI     │◄──►│ MCP Server       │◄──►│ Meta Marketing  │\n│                 │    │                  │    │ API             │\n│ - Natural       │    │ - Authentication │    │                 │\n│   Language      │    │ - Rate Limiting  │    │ - Campaigns     │\n│ - Tool Calls    │    │ - Error Handling │    │ - Analytics     │\n│ - Resource      │    │ - Data Transform │    │ - Audiences     │\n│   Access        │    │ - Pagination     │    │ - Creatives     │\n└─────────────────┘    └──────────────────┘    └─────────────────┘\n```\n\n### Core Components\n\n- **Meta API Client**: Handles authentication, rate limiting, and API communication\n- **Tool Handlers**: 25 tools covering analytics, campaigns, ad sets, ads, audiences, creatives, and diagnostics\n- **Resource Providers**: Contextual data access for AI understanding\n- **Error Management**: Robust error handling with automatic retries\n- **Rate Limiter**: Intelligent rate limiting with per-account tracking\n\n## 🔒 Security & Best Practices\n\n### Token Security\n- ✅ Environment variable configuration\n- ✅ No token logging or exposure\n- ✅ Automatic token validation\n- ✅ Secure credential management\n\n### API Management\n- ✅ Rate limit compliance\n- ✅ Exponential backoff retries\n- ✅ Request validation\n- ✅ Error boundary protection\n\n### Data Privacy\n- ✅ Meta data use policy compliance\n- ✅ No persistent data storage\n- ✅ Secure API communication\n- ✅ Audit trail support\n\n## ⚡ Performance\n\n### Rate Limits\n- **Development Tier**: 60 API calls per 5 minutes\n- **Standard Tier**: 9000 API calls per 5 minutes\n- **Automatic Management**: Built-in rate limiting and retry logic\n\n### Optimization\n- 🚀 Concurrent request processing\n- 📦 Efficient pagination handling\n- 🎯 Smart data caching\n- ⚡ Minimal memory footprint\n\n## 🧪 Testing\n\nRun the test suite:\n```bash\nnpm test\n```\n\nTest with example client:\n```bash\nnpx tsx examples/client-example.ts\n```\n\nHealth check:\n```bash\n# In Claude:\nCheck the health of the Meta Marketing API server\n```\n\n## 🤝 Contributing\n\n1. Fork the repository\n2. Create a feature branch: `git checkout -b feature/new-feature`\n3. Make your changes and add tests\n4. Run the test suite: `npm test`\n5. Submit a pull request\n\n## 📄 License\n\nMIT License - see [LICENSE](LICENSE) for details.\n\n## 🆘 Support\n\n- **Documentation**: See this README\n- **Issues**: Open an issue on GitHub\n- **Meta API**: Refer to [Meta Marketing API docs](https://developers.facebook.com/docs/marketing-apis/)\n- **MCP Protocol**: See [Model Context Protocol specification](https://modelcontextprotocol.io/)\n\n---\n\nBuilt for reliable Meta Marketing API automation with MCP.\n","readmeFilename":"README.md"}