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

Clone the repository:

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

Install dependencies:
```
npm install
```
Create a .env file based on .env.example:
```
cp .env.example .env
```
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

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.

Create a new project on Railway
Connect your GitHub repository
Add the required environment variables in the Railway dashboard
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.