facebook-ads-mcp

# 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: ```bash git clone https://github.com/yourusername/facebook-ads-mcp.git cd facebook-ads-mcp ``` 2. Install dependencies: ```bash npm install ``` 3. Create a `.env` file based on `.env.example`: ```bash 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: ```bash 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](https://railway.app/) 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.