# Meta (Facebook) Developer Apps MCP (`was-meta-apps-mcp`)

A self-contained, cross-platform Model Context Protocol (MCP) server for managing Meta (Facebook) Developer applications. Exposes 14 tools allowing AI coding assistants (Claude Desktop, Cursor, Antigravity, VS Code, Zed, etc.) to discover apps, update configurations, manage team roles, configure webhooks, monitor permissions, create test users, and invoke the Meta Graph API directly. Built by Web Analytics Solution.

## Prerequisites

| | Required | How to install |
|---|---|---|
| **Node.js 18+** | running `npx` | Mac: `brew install node` · Windows: https://nodejs.org · Linux: `apt install nodejs npm` |
| **Git** | letting `npx` clone from GitHub | Mac: `brew install git` (or first `git --version` triggers Xcode tools) · Windows: https://git-scm.com · Linux: `apt install git` |
| **Meta Developer Account** | to access Developer Apps | [Meta for Developers](https://developers.facebook.com/) |
| **Meta Access Token** | for authentication | Walked through below |

## Quick Start — 3 Steps

### Step 1 — Get Access Token

1. Go to the [Meta Graph API Explorer](https://developers.facebook.com/tools/explorer/).
2. Select your Meta App in the top dropdown (or create one at [developers.facebook.com/apps](https://developers.facebook.com/apps)).
3. Under **User or Page**, select **User Token** or create a **System User Token** in Meta Business Settings.
4. Add permissions as needed (e.g., `ads_management`, `business_management`, `email`).
5. Click **Generate Access Token**.
6. *(Optional)* Find your **App Secret** under **App Settings > Basic** if you want automatic `appsecret_proof` calculation.

### Step 2 — Connect

Run the interactive setup command in your terminal:

```bash
npx -y github:mnsmasum62786/was-meta-apps-mcp auth
```

1. Paste your **Meta Access Token** when prompted.
2. *(Optional)* Paste your **App Secret** (or press Enter to skip).
3. *(Optional)* Paste your default **App ID** (or press Enter to skip).
4. The CLI will verify your token against the Meta Graph API and save credentials locally at `~/.was-meta-apps-mcp/config.json` with secure `0600` permissions.

### Step 3 — Add to Your AI Client

Add the following configuration to your AI client's MCP configuration JSON file:

```json
{
  "mcpServers": {
    "Meta Apps MCP": {
      "command": "npx",
      "args": ["-y", "github:mnsmasum62786/was-meta-apps-mcp"]
    }
  }
}
```

#### Configuration File Locations by Client:
- **Claude Desktop (Mac)**: `~/Library/Application Support/Claude/claude_desktop_config.json`
- **Claude Desktop (Windows)**: `%APPDATA%\Claude\claude_desktop_config.json`
- **Cursor**: `~/.cursor/mcp.json` (or via Cursor Settings -> MCP)
- **Google Antigravity / Windsurf**: `~/.gemini/antigravity/mcp.json` or `~/.codeium/windsurf/mcp_config.json`

## What You Can Ask the AI

### Discovery & Inspection
- *"List all the Meta developer apps I have access to."*
- *"Show me the settings, allowed domains, and contact email for app ID `123456789`."*
- *"What permissions and features does my app currently have approved?"*

### App Configuration
- *"Update my Meta app's privacy policy URL to `https://example.com/privacy` and contact email to `admin@example.com`."*
- *"Add `example.com` and `api.example.com` to my app's allowed domains."*
- *"Set server IP whitelist for my app to `192.0.2.1`."*

### Roles & Team Management
- *"List all administrators and developers on my Meta app."*
- *"Add user ID `987654321` as a tester to my app."*
- *"Remove user ID `987654321` from the app roles."*

### Webhooks & Subscriptions
- *"List all active webhook subscriptions for my app."*
- *"Subscribe my app to `page` webhook events for `messages` and `feed` with callback `https://example.com/webhook`."*
- *"Delete the `permissions` webhook subscription."*

### Sandbox Testing
- *"List all test users created for this app."*
- *"Create a new test user named 'Test John' with `email` and `public_profile` permissions."*

### Universal Graph API
- *"Query the Graph API endpoint `/me/accounts` to see connected Facebook Pages."*

## All Tools (14 Total)

| Category | Tools | Description |
|---|---|---|
| **App Discovery** | `meta_list_apps` | List all Meta developer apps accessible by the current token. |
| | `meta_get_app` | Get detailed settings, domains, and metadata for a specific app. |
| **App Settings** | `meta_update_app` | Update app details, URLs, domains, and server IP whitelists. |
| **Role Management** | `meta_list_roles` | List all admins, developers, testers, and insights users. |
| | `meta_add_role` | Add a user role (administrator, developer, tester, insights user). |
| | `meta_remove_role` | Remove a user role from the app. |
| **Webhooks** | `meta_list_subscriptions` | List webhook subscriptions configured on the app. |
| | `meta_create_subscription` | Subscribe or update webhook endpoints (user, page, instagram, etc.). |
| | `meta_delete_subscription` | Remove a webhook subscription from the app. |
| **Permissions** | `meta_list_permissions` | Check review status and approved permissions/features. |
| **Testing Sandbox** | `meta_list_test_users` | List test users created under the app. |
| | `meta_create_test_user` | Create a test user with pre-granted permissions. |
| | `meta_delete_test_user` | Delete a test user. |
| **Universal API** | `meta_graph_api` | Universal escape hatch: call any Meta Graph API endpoint directly. |

## CLI Commands

You can run these commands directly via `npx -y github:mnsmasum62786/was-meta-apps-mcp <command>`:

- `auth` — Interactive prompt to connect or re-connect Meta credentials.
- `status` — Show config file location and summary of saved credentials.
- `logout` — Delete the locally stored credentials file (`~/.was-meta-apps-mcp/config.json`).
- `help` — Print command line usage and environment variable options.

## Multi-Account Setup

You can bypass the local config file by setting environment variables in your client configuration. This allows running multiple Meta accounts or apps simultaneously:

```json
{
  "mcpServers": {
    "Meta Developer (Personal)": {
      "command": "npx",
      "args": ["-y", "github:mnsmasum62786/was-meta-apps-mcp"],
      "env": {
        "META_ACCESS_TOKEN": "EAA...",
        "META_APP_ID": "111111111111"
      }
    },
    "Meta Developer (Agency)": {
      "command": "npx",
      "args": ["-y", "github:mnsmasum62786/was-meta-apps-mcp"],
      "env": {
        "META_ACCESS_TOKEN": "EAA...",
        "META_APP_SECRET": "abc123secret",
        "META_APP_ID": "222222222222"
      }
    }
  }
}
```

## Troubleshooting

### 1. "Meta (Facebook) Developer Apps MCP — not configured yet"
- **Cause**: The MCP server was started before configuring credentials.
- **Fix**: Open your terminal and run `npx -y github:mnsmasum62786/was-meta-apps-mcp auth`.

### 2. "Token verification failed (HTTP 400 / 401)"
- **Cause**: The token has expired, or the user/system token does not have adequate permissions.
- **Fix**: Generate a fresh token from [Graph API Explorer](https://developers.facebook.com/tools/explorer/) and run `auth` again.

### 3. Windows PowerShell Execution Policy Error
If you see an error like `npx.ps1 cannot be loaded because running scripts is disabled`:
- **Fix**: Run the following command in PowerShell:
  ```powershell
  Set-ExecutionPolicy -Scope CurrentUser -ExecutionPolicy RemoteSigned
  ```

### 4. Cache Issues after Updates
To force clear the npx cache and download the latest release:
- **Windows (PowerShell)**:
  ```powershell
  Remove-Item -Recurse -Force "$env:LOCALAPPDATA\npm-cache" -ErrorAction SilentlyContinue
  npm cache clean --force
  ```
- **Mac / Linux**:
  ```bash
  rm -rf ~/.npm/_npx
  npm cache clean --force
  ```

## License

MIT License. Built by [Web Analytics Solution](https://webanalyticsbd.com/).