Facebook Ads Management Control Panel (MCP)

A comprehensive Node.js Express server that integrates with the Facebook Marketing API to provide a robust platform for managing Facebook ad campaigns, analyzing performance, and receiving optimization recommendations.

Features

• Facebook OAuth Authentication: Secure login with Facebook credentials
• Ad Account Management: View and manage multiple Facebook ad accounts
• Campaign Management: Create, read, update, and delete campaigns
• Ad Set Management: Create, read, update, and delete ad sets with targeting options
• Ad Management: Create, read, update, and delete ads with creative options
• Analytics: Comprehensive analytics for campaigns, ad sets, and ads
• Recommendations: Intelligent recommendations for budget optimization, targeting, and creative performance
• API Documentation: Detailed API documentation for all endpoints
• Railway Deployment: Easy deployment to Railway with minimal configuration

Tech Stack

• Backend: Node.js, Express
• Database: MongoDB with Mongoose ODM
• Authentication: Passport.js with Facebook OAuth, JWT
• API Integration: Facebook Marketing API
• Validation: Joi
• Logging: Winston
• Security: Helmet, CORS, Rate Limiting, CSRF Protection
• Deployment: Railway

Project Structure

facebook-ads-mcp/
├── src/
│   ├── config/             # Configuration files
│   ├── middleware/         # Express middleware
│   ├── models/             # Mongoose models
│   ├── routes/             # API routes
│   ├── services/           # Business logic
│   ├── utils/              # Utility functions
│   └── app.js              # Express app setup
├── server.js               # Server entry point
├── .env.example            # Environment variables example
├── package.json            # Dependencies and scripts
├── railway.json            # Railway deployment config
└── README.md               # Project documentation

Prerequisites

• Node.js (v14 or higher)
• MongoDB database (local or Atlas)
• Facebook Developer Account with an app that has Marketing API permissions

Getting Started

Installation

1. Clone the repository:

   git clone https://github.com/yourusername/facebook-ads-mcp.git
   cd facebook-ads-mcp
   

2. Install dependencies:

   npm install
   

3. Create a .env file based on .env.example:

   cp .env.example .env
   

4. Update the .env file with your configuration:

   • MongoDB connection string
   • Facebook App ID and Secret
   • JWT secret key
   • Other configuration options

Running Locally

Start the development server:

npm run dev

The server will be available at http://localhost:3000.

API Endpoints

Authentication

• GET /auth/facebook: Initiate Facebook OAuth flow
• GET /auth/facebook/callback: Handle Facebook OAuth callback
• POST /auth/refresh: Refresh JWT token
• POST /auth/logout: Logout user
• GET /auth/me: Get current user
• PUT /auth/me: Update current user

Ad Accounts

• GET /api/ad-accounts: Get all ad accounts
• GET /api/ad-accounts/sync: Sync ad accounts from Facebook
• GET /api/ad-accounts/:id: Get ad account by ID
• GET /api/ad-accounts/:id/insights: Get insights for an ad account
• GET /api/ad-accounts/:id/campaigns: Get campaigns for an ad account

Campaigns

• GET /api/campaigns: Get all campaigns
• GET /api/campaigns/sync: Sync campaigns from Facebook
• POST /api/campaigns: Create a new campaign
• GET /api/campaigns/:id: Get campaign by ID
• PUT /api/campaigns/:id: Update campaign
• DELETE /api/campaigns/:id: Delete campaign
• GET /api/campaigns/:id/insights: Get insights for a campaign
• GET /api/campaigns/:id/adsets: Get ad sets for a campaign
• GET /api/campaigns/:id/analytics: Get analytics for a campaign
• POST /api/campaigns/:id/fetch-analytics: Fetch and store analytics for a campaign

Ad Sets

• GET /api/ad-sets: Get all ad sets
• GET /api/ad-sets/sync: Sync ad sets from Facebook
• POST /api/ad-sets: Create a new ad set
• GET /api/ad-sets/:id: Get ad set by ID
• PUT /api/ad-sets/:id: Update ad set
• DELETE /api/ad-sets/:id: Delete ad set
• GET /api/ad-sets/:id/insights: Get insights for an ad set
• GET /api/ad-sets/:id/ads: Get ads for an ad set
• GET /api/ad-sets/:id/analytics: Get analytics for an ad set
• POST /api/ad-sets/:id/fetch-analytics: Fetch and store analytics for an ad set
• GET /api/ad-sets/:id/targeting-recommendations: Get targeting recommendations for an ad set

Ads

• GET /api/ads: Get all ads
• GET /api/ads/sync: Sync ads from Facebook
• POST /api/ads: Create a new ad
• GET /api/ads/:id: Get ad by ID
• PUT /api/ads/:id: Update ad
• DELETE /api/ads/:id: Delete ad
• GET /api/ads/:id/insights: Get insights for an ad
• GET /api/ads/:id/analytics: Get analytics for an ad
• POST /api/ads/:id/fetch-analytics: Fetch and store analytics for an ad
• GET /api/ads/:id/creative-recommendations: Get creative recommendations for an ad
• GET /api/ads/:id/preview: Get preview URL for an ad

Analytics

• GET /api/analytics/overview: Get account overview analytics
• GET /api/analytics/campaigns: Get analytics for all campaigns
• GET /api/analytics/campaigns/:id: Get analytics for a specific campaign
• GET /api/analytics/ad-sets: Get analytics for all ad sets
• GET /api/analytics/ad-sets/:id: Get analytics for a specific ad set
• GET /api/analytics/ads: Get analytics for all ads
• GET /api/analytics/ads/:id: Get analytics for a specific ad
• POST /api/analytics/fetch: Fetch and store analytics for all entities
• GET /api/analytics/comparison: Get performance comparison between two time periods
• GET /api/analytics/metrics: Get available metrics for analytics

Recommendations

• GET /api/recommendations/budget: Get budget optimization recommendations
• GET /api/recommendations/targeting: Get targeting recommendations for an ad set
• GET /api/recommendations/creative: Get creative performance recommendations
• GET /api/recommendations/all: Get all recommendations for an ad account
• GET /api/recommendations/summary: Get recommendations summary for an ad account
• GET /api/recommendations/best-practices: Get best practices recommendations

Health Check

• GET /health: Health check endpoint
• GET /health/db: Database health check endpoint
• GET /health/deep: Deep health check endpoint

Deployment to Railway

This project is configured for easy deployment to Railway.

1. Create a new project on Railway

2. Connect your GitHub repository

3. Add the required environment variables in the Railway dashboard

4. Deploy the project

The railway.json file in the repository configures the deployment settings, including the health check endpoint and restart policy.

Security Considerations

This project implements several security measures:

• Authentication: JWT-based authentication with secure cookies
• Rate Limiting: Prevents brute force attacks
• CSRF Protection: Prevents cross-site request forgery
• Helmet: Sets various HTTP headers for security
• Input Validation: Validates all input data using Joi
• MongoDB Sanitization: Prevents NoSQL injection
• XSS Protection: Prevents cross-site scripting attacks

Contributing

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

License

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