Meta MCP Server

A personal MCP Server implementation for the Meta Marketing API, designed for both stdio (Claude, etc.) and SSE (n8n) workflows. This is not an official Meta product.

Installation

# Global installation (recommended for n8n usage)
npm install -g @dro-ff/meta-mcp

# Or run directly with npx (recommended for stdio usage)
npx @dro-ff/meta-mcp

Configuration

Meta API Credentials

Set the following environment variables for Meta API authentication:

META_APP_ID=your_app_id
META_APP_SECRET=your_app_secret
META_ACCESS_TOKEN=your_access_token
META_BUSINESS_ID=your_business_id
META_SYSTEM_USER_ID=your_system_user_id
META_PAGE_ID=your_page_id
META_ACCOUNT_ID=your_account_id
META_API_VERSION=v22.0  # Optional, defaults to v22.0

Server Configuration (for SSE transport)

Optional environment variables for SSE server configuration:

MCP_TRANSPORT=sse  # 'sse' or 'stdio' (defaults to 'sse' if not specified)
MCP_HOST=localhost  # Server host (defaults to localhost)
MCP_PORT=3000      # Server port (defaults to 3000)
NODE_ENV=development  # or production

Usage Methods

This MCP server supports two transport methods:

1. stdio Transport (for Claude, etc.)

Add the following to your application's configuration (e.g., claude_desktop_config.json):

{
  "mcpServers": {
    "meta-marketing": {
      "command": "npx",
      "args": ["@dro-ff/meta-mcp"],
      "env": {
        "META_APP_ID": "your_app_id",
        "META_APP_SECRET": "your_app_secret",
        "META_ACCESS_TOKEN": "your_access_token",
        "META_BUSINESS_ID": "your_business_id",
        "META_SYSTEM_USER_ID": "your_system_user_id",
        "META_PAGE_ID": "your_page_id",
        "META_ACCOUNT_ID": "your_account_id",
        "META_API_VERSION": "v22.0"
      }
    }
  }
}

2. SSE Transport (for n8n)

1. Start the MCP Server:

meta-mcp
# Server will start at http://localhost:3000 by default

2. In n8n:
   • Add an MCP Client node
   • Configure the connection:
     • Connection Type: SSE
     • Base URL: http://localhost:3000 (or your server address)
     • Initial Connection Path: /connect
   • Add Meta API credentials in n8n's interface
   • Use the available capabilities in your workflows

The server automatically handles both transport methods based on how it's initiated. No additional configuration is needed to switch between them.

Available Capabilities

Resources

• Campaigns: List and get campaigns
• Ad Sets: List and get ad sets
• Ads: List and get ads
• Creatives: List and get creatives

Tools

• Campaign Tools:
  • Create campaigns
  • Update campaigns
  • Get campaign insights
• Ad Set Tools:
  • Create ad sets
  • Get ad set insights
• Ad Tools:
  • Create ads (requires app in Live status)
  • Get ad insights
• Creative Tools:
  • Get creative insights

Prompts

• Campaign Insights Analysis: Analyze campaign performance with optional funnel analysis

Development

1. Clone the repository:

git clone https://github.com/DSRoden/meta-mcp-server.git
cd meta-mcp-server

2. Install dependencies:

npm install

3. Build the project:

npm run build

4. Start the server:

# Development mode with hot reload
npm run dev

# Production mode
npm start

# Run with specific transport
MCP_TRANSPORT=sse npm start

5. Run the MCP Inspector:

# One-time inspection
npm run inspect

# Development mode with inspector
npm run dev:inspect

Server Endpoints (SSE Mode)

When running in SSE mode, the following endpoints are available:

• GET /health - Health check endpoint
• GET /connect - Initial SSE connection
• GET /mcp?sessionId={sessionId} - SSE stream endpoint
• POST /mcp?sessionId={sessionId} - JSON-RPC endpoint for commands

Environment Variables Summary

| Variable | Required | Default | Description | | ------------------- | -------- | ----------- | -------------------------- | | META_APP_ID | Yes | - | Meta App ID | | META_APP_SECRET | Yes | - | Meta App Secret | | META_ACCESS_TOKEN | Yes | - | Meta Access Token | | META_BUSINESS_ID | Yes | - | Meta Business ID | | META_SYSTEM_USER_ID | Yes | - | Meta System User ID | | META_PAGE_ID | Yes | - | Meta Page ID | | META_ACCOUNT_ID | Yes | - | Meta Ad Account ID | | META_API_VERSION | No | v22.0 | Meta API Version | | MCP_TRANSPORT | No | sse | Transport type (sse/stdio) | | MCP_HOST | No | localhost | Server host (SSE mode) | | MCP_PORT | No | 3000 | Server port (SSE mode) | | NODE_ENV | No | development | Environment mode |

License

MIT

Backend Integration

Express.js Server Integration

You can integrate the MCP server into your existing Express.js backend:

import express from "express";
import { Server } from "@dro-ff/meta-mcp";
import { SSEServerTransport } from "@modelcontextprotocol/sdk/server/sse.js";
import dotenv from "dotenv";

// ... rest of server code as before ...

Node.js Client Integration

To interact with the MCP server from another Node.js application, use the MCP client:

import { Client } from "@modelcontextprotocol/sdk/client/index.js";
import { SSEClientTransport } from "@modelcontextprotocol/sdk/client/sse.js";

async function main() {
  // Initialize the client
  const client = new Client(
    {
      name: "meta-marketing-client",
      version: "1.0.0",
    },
    {
      capabilities: {},
    }
  );

  try {
    // Connect to MCP server using SSE transport
    const transport = new SSEClientTransport({
      baseUrl: "http://localhost:3000", // Your MCP server URL
      connectPath: "/connect",
    });

    await client.connect(transport);
    console.log("Connected to MCP server");

    // Example: Create a campaign
    const result = await client.request({
      method: "tools/call",
      params: {
        name: "mcp_meta_mcp_meta_campaign_create",
        arguments: {
          name: "Test Campaign",
          objective: "OUTCOME_AWARENESS",
          status: "PAUSED",
          special_ad_categories: [],
        },
      },
    });

    console.log("Campaign created:", result);

    // Example: Get campaign insights
    const insights = await client.request({
      method: "tools/call",
      params: {
        name: "mcp_meta_mcp_meta_campaign_insights",
        arguments: {
          campaign_id: result.id,
          date_preset: "last_7d",
        },
      },
    });

    console.log("Campaign insights:", insights);
  } catch (error) {
    console.error("Error:", error);
  }
}

main();

Using stdio Transport in Node.js

For stdio transport (useful for CLI tools or desktop apps):

import { Client } from "@modelcontextprotocol/sdk/client/index.js";
import { StdioClientTransport } from "@modelcontextprotocol/sdk/client/stdio.js";

async function main() {
  const client = new Client(
    {
      name: "meta-marketing-client",
      version: "1.0.0",
    },
    {
      capabilities: {},
    }
  );

  try {
    // Connect using stdio transport
    const transport = new StdioClientTransport({
      command: "npx",
      args: ["@dro-ff/meta-mcp"],
      env: {
        META_APP_ID: process.env.META_APP_ID,
        META_APP_SECRET: process.env.META_APP_SECRET,
        META_ACCESS_TOKEN: process.env.META_ACCESS_TOKEN,
        META_BUSINESS_ID: process.env.META_BUSINESS_ID,
        META_SYSTEM_USER_ID: process.env.META_SYSTEM_USER_ID,
        META_PAGE_ID: process.env.META_PAGE_ID,
        META_ACCOUNT_ID: process.env.META_ACCOUNT_ID,
        META_API_VERSION: process.env.META_API_VERSION,
      },
    });

    await client.connect(transport);
    console.log("Connected to MCP server via stdio");

    // Make requests as in the SSE example
  } catch (error) {
    console.error("Error:", error);
  }
}

main();

Example: Express.js Application with Both Server and Client

Here's a complete example combining both server and client in an Express application:

import express from "express";
import { Server } from "@dro-ff/meta-mcp";
import { Client } from "@modelcontextprotocol/sdk/client/index.js";
import { SSEServerTransport } from "@modelcontextprotocol/sdk/server/sse.js";
import { SSEClientTransport } from "@modelcontextprotocol/sdk/client/sse.js";
import dotenv from "dotenv";

dotenv.config();
const app = express();
const port = process.env.PORT || 3000;

// Initialize Express middleware
app.use(express.json());

// Initialize MCP Server
const mcpServer = new Server(
  {
    name: "meta-marketing-server",
    version: "1.0.0",
  },
  {
    capabilities: {
      tools: { list: true, call: true },
      resources: { list: true, read: true, templates: true },
      prompts: { list: true, get: true },
    },
  }
);

// Initialize MCP Client
const mcpClient = new Client(
  {
    name: "meta-marketing-client",
    version: "1.0.0",
  },
  {
    capabilities: {},
  }
);

// Example API endpoint using MCP client
app.post("/api/campaigns", async (req, res) => {
  try {
    const result = await mcpClient.request({
      method: "tools/call",
      params: {
        name: "mcp_meta_mcp_meta_campaign_create",
        arguments: req.body,
      },
    });
    res.json(result);
  } catch (error) {
    res.status(500).json({ error: error.message });
  }
});

// Mount MCP server endpoints
app.get("/mcp/connect", async (req, res) => {
  // ... SSE connection handling as before ...
});

app.post("/mcp", async (req, res) => {
  // ... MCP message handling as before ...
});

// Start the server
app.listen(port, async () => {
  console.log(`Server running at http://localhost:${port}`);

  // Connect MCP client to the server
  try {
    const transport = new SSEClientTransport({
      baseUrl: `http://localhost:${port}`,
      connectPath: "/connect",
    });
    await mcpClient.connect(transport);
    console.log("MCP client connected successfully");
  } catch (error) {
    console.error("Failed to connect MCP client:", error);
  }
});

Deployment Examples

// ... rest of existing deployment content ...