npm package: @qressy/qressy-meta-ads-mcp
Description: MCP bridge for Meta Ads API - connects Cursor/Claude to the cloud-hosted Meta Ads MCP server
Author: Qressy
Latest version: 1.0.3

# @qressy/qressy-meta-ads-mcp

[![npm version](https://img.shields.io/npm/v/@qressy/qressy-meta-ads-mcp.svg)](https://www.npmjs.com/package/@qressy/qressy-meta-ads-mcp)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
[![TypeScript](https://img.shields.io/badge/TypeScript-5.3-blue.svg)](https://www.typescriptlang.org/)

**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](https://developers.facebook.com/) with `ads_read` permission

## Quick Start

### Installing

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

Or use directly with npx (no installation needed):

```bash
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`

   ```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](https://developers.facebook.com/)
   - 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](https://github.com/qressy/qressy-meta-ads-mcp#available-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:
   ```bash
   npm install @qressy/qressy-meta-ads-mcp
   ```

## Development

```bash
# 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](LICENSE) file for details.

## Repository

- **GitHub:** [github.com/qressy/qressy-meta-ads-mcp](https://github.com/qressy/qressy-meta-ads-mcp)
- **Issues:** [Report an issue](https://github.com/qressy/qressy-meta-ads-mcp/issues)
- **Releases:** [View releases](https://github.com/qressy/qressy-meta-ads-mcp/releases)

## Support

For questions, issues, or feature requests, please [open an issue](https://github.com/qressy/qressy-meta-ads-mcp/issues) on GitHub.

---

Made with ❤️ by [Qressy](https://github.com/qressy)