@qressy/qressy-meta-ads-mcp

MCP bridge for Meta Ads API - Connects Cursor and Claude Desktop to the cloud-hosted Meta Ads MCP server via stdio.

With this package, you can:

• Access 40+ Meta Ads API tools directly from Cursor or Claude Desktop
• Manage ad campaigns, ad sets, and ads programmatically
• Get insights and analytics for your Facebook/Meta advertising
• Zero configuration - just add your Meta token and start using

Before you begin

• Install Node.js 18+ and npm (or another package manager)
• Get your Meta Access Token from the Meta Developer Portal with ads_read permission

Quick Start

Installing

npm install -g @qressy/qressy-meta-ads-mcp

Or use directly with npx (no installation needed):

npx @qressy/qressy-meta-ads-mcp

Setup (Plug and Play)

1. Add to your Cursor or Claude Desktop MCP config:

   macOS: ~/Library/Application Support/Cursor/claude_desktop_config.json
   Windows: %APPDATA%\Cursor\claude_desktop_config.json
   Linux: ~/.config/Cursor/claude_desktop_config.json

   {
     "mcpServers": {
       "meta-ads-mcp": {
         "command": "npx",
         "args": ["-y", "@qressy/qressy-meta-ads-mcp@latest"],
         "env": {
           "META_TOKEN": "YOUR_META_ACCESS_TOKEN"
         }
       }
     }
   }

2. Get your Meta Access Token:

   • Go to Meta Developer Portal
   • Create an app or use an existing one
   • Generate a User Access Token with ads_read permission
   • Copy the token and paste it in the config above

3. Restart Cursor or Claude Desktop - The tools will appear automatically!

Available Tools

This package provides 40+ tools for Meta Ads API, including:

Account Management

• list_ad_accounts - List all ad accounts
• get_details_of_ad_account - Get account details
• get_adaccount_insights - Get performance insights

Campaign Management

• get_campaigns_by_adaccount - List campaigns
• get_campaign_by_id - Get campaign details
• get_campaign_insights - Get campaign performance
• pause_campaign / resume_campaign - Control campaign status
• update_campaign_budget - Update campaign budgets

Ad Set Management

• get_adsets_by_campaign - List ad sets
• get_adset_by_id - Get ad set details
• get_adset_insights - Get ad set performance
• pause_adset / resume_adset - Control ad set status
• update_adset_budget - Update ad set budgets

Ad Management

• get_ads_by_adset - List ads
• get_ad_by_id - Get ad details
• get_ad_insights - Get ad performance
• pause_ad / resume_ad - Control ad status

Page Analytics

• analyze_page - Comprehensive page analysis
• get_page_insights - Page performance metrics
• analyze_page_posts - Analyze multiple posts
• get_audience_insights - Audience demographics

...and many more! See the full list of tools.

Environment Variables

| Variable | Required | Description | |----------|----------|-------------| | META_TOKEN | ✅ Yes | Your Meta access token (with ads_read permission) | | MCP_SERVER_URL | ❌ No | Default: production Lambda URL. Override for custom deployment. | | LICENSE_KEY | ❌ No | License key if your server requires it | | MCP_DEBUG | ❌ No | Set to 1 or true for debug logs |

Installation from GitHub Packages

If you're using GitHub Packages instead of npm:

1. Create a .npmrc file in your home directory:

   @qressy:registry=https://npm.pkg.github.com
   //npm.pkg.github.com/:_authToken=YOUR_GITHUB_TOKEN

2. Install:

   npm install @qressy/qressy-meta-ads-mcp

Development

# Clone the repository
git clone https://github.com/qressy/qressy-meta-ads-mcp.git
cd qressy-meta-ads-mcp

# Install dependencies
npm install

# Build
npm run build

# Test locally
npm start

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

1. Fork the repository
2. Create your feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add some amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

License

This project is licensed under the MIT License - see the LICENSE file for details.

Repository

• GitHub: github.com/qressy/qressy-meta-ads-mcp
• Issues: Report an issue
• Releases: View releases

Support

For questions, issues, or feature requests, please open an issue on GitHub.

Made with ❤️ by Qressy