mcp-meta-inbox

MCP server that wraps the Meta Messenger Platform, Instagram Messaging and comment moderation APIs (Graph API v25.0) as semantic tools for LLM agents.

Read your Page inbox, reply to students, and moderate comments on Facebook posts and Instagram media — from natural language.

Works with Claude Code, Codex, Claude Desktop, Cursor, VS Code, Windsurf, and any MCP-compatible client.

Companion to mcp-meta-marketing, which covers ads. They do not share a token — see Why not the Marketing API token.

Quick Start

claude mcp add meta-inbox -s user \
  -e META_PAGE_ACCESS_TOKEN=your-page-token \
  -e META_PAGE_ID=your-page-id \
  -- npx -y github:pauloFroes/mcp-meta-inbox

Then just ask in natural language:

Don't have a Page token yet? See How to get your Page Access Token below.

Related MCP server: facebook-pages-mcp

What you can do

Work the inbox:

"Who messaged the Page today and what did they ask?"
"Summarize the last 20 conversations and flag the ones still unanswered"
"Read thread t_1997631717587281 and draft a reply about the course schedule"
"Mark Sandro's conversation as seen"

Moderate comments:

"List the comments on my latest Instagram post"
"Which comments are questions nobody answered?"
"Reply to that comment asking about the price"
"Hide the spam comment on last week's Facebook post"
"Answer that public question privately instead"

Availability at a glance

Instagram Direct is gated by Meta, not by this server. Without Advanced Access the API answers a /conversations?platform=instagram call with a ~27s timeout (error_subcode: 2534084) explaining that too many threads belong to people with no role on the app. Instagram comments are unaffected and work today. The tools are shipped anyway so they start working the moment App Review clears — and check_access tells you where you stand.

Available Tools

Diagnostics

Inbox

Posts and comments

Platform asymmetries worth knowing

These are Meta's limits, surfaced as clear tool errors rather than opaque failures:

Messaging windows

The two ways to DM someone have different clocks, and confusing them is how a stale inbox comes to look like a work queue right up until every send fails.

The 24-hour limit is Meta's standard messaging window — "Businesses have up to 24 hours to respond to a user" (Messenger Platform policy). It is not a WhatsApp-only rule.

Pass tag only when it honestly describes the message: HUMAN_AGENT (a human answering the person's own question), ACCOUNT_UPDATE, CONFIRMED_EVENT_UPDATE, POST_PURCHASE_UPDATE. Sending off-purpose is a policy violation, and HUMAN_AGENT also needs the Human Agent feature approved for the app — without it Meta rejects the call.

Because private_reply is measured from the comment rather than from a message, it is usually the only live channel: a comment posted this morning is reachable for a week, while an inbox thread that went quiet yesterday is already closed.

Installation

You need two environment variables (a third is optional):

Claude Code

Three installation scopes are available:

Quick setup (inline env vars):

claude mcp add meta-inbox -s user \
  -e META_PAGE_ACCESS_TOKEN=your-page-token \
  -e META_PAGE_ID=your-page-id \
  -- npx -y github:pauloFroes/mcp-meta-inbox

Persistent setup (.env file):

Add to your .mcp.json:

{
  "meta-inbox": {
    "command": "npx",
    "args": ["-y", "github:pauloFroes/mcp-meta-inbox"],
    "env": {
      "META_PAGE_ACCESS_TOKEN": "${META_PAGE_ACCESS_TOKEN}",
      "META_PAGE_ID": "${META_PAGE_ID}",
      "META_IG_USER_ID": "${META_IG_USER_ID}"
    }
  }
}

Then define the values in your .env file. See .env.example.

Codex

[mcp_servers.meta-inbox]
command = "npx"
args = ["-y", "github:pauloFroes/mcp-meta-inbox"]
env_vars = ["META_PAGE_ACCESS_TOKEN", "META_PAGE_ID", "META_IG_USER_ID"]

Claude Desktop

Add to claude_desktop_config.json:

{
  "mcpServers": {
    "meta-inbox": {
      "command": "npx",
      "args": ["-y", "github:pauloFroes/mcp-meta-inbox"],
      "env": {
        "META_PAGE_ACCESS_TOKEN": "your-page-token",
        "META_PAGE_ID": "your-page-id"
      }
    }
  }
}

Cursor

Add to ~/.cursor/mcp.json:

{
  "mcpServers": {
    "meta-inbox": {
      "command": "npx",
      "args": ["-y", "github:pauloFroes/mcp-meta-inbox"],
      "env": {
        "META_PAGE_ACCESS_TOKEN": "your-page-token",
        "META_PAGE_ID": "your-page-id"
      }
    }
  }
}

VS Code

Add to .vscode/mcp.json in your project:

{
  "servers": {
    "meta-inbox": {
      "command": "npx",
      "args": ["-y", "github:pauloFroes/mcp-meta-inbox"],
      "env": {
        "META_PAGE_ACCESS_TOKEN": "your-page-token",
        "META_PAGE_ID": "your-page-id"
      }
    }
  }
}

Windsurf

Add to ~/.codeium/windsurf/mcp_config.json:

{
  "mcpServers": {
    "meta-inbox": {
      "command": "npx",
      "args": ["-y", "github:pauloFroes/mcp-meta-inbox"],
      "env": {
        "META_PAGE_ACCESS_TOKEN": "your-page-token",
        "META_PAGE_ID": "your-page-id"
      }
    }
  }
}

Why not the Marketing API token

If you already run mcp-meta-marketing, the obvious move is to reuse its META_ACCESS_TOKEN. It does not work here.

That token is normally a System User token. The Conversations API rejects System User tokens — but it does not say so. It answers:

{"error":{"message":"An unexpected error has occurred. Please retry your request later.",
          "type":"OAuthException","code":2,"is_transient":true}}

…which reads like a transient server fault and is identical across API versions. Retrying never helps. The inbox needs a Page token that was requested by a person with the MODERATE task on the Page.

This server refuses to start if it finds META_ACCESS_TOKEN but no META_PAGE_ACCESS_TOKEN, and prints how to fix it. Run check_access any time you're unsure which kind of token you're holding.

Instagram comments happen to work with either token. Everything else needs the Page token, so this server standardizes on it.

How to get your Page Access Token

Requires an existing Meta App with the Messenger and Instagram use cases added, and a Business Portfolio that owns the Page.

1. Go to developers.facebook.com → your app → Use cases

2. Open "Interact with customers on Messenger from Meta" → Customize

3. In the left menu, pick Messenger API settings

4. Under 2. Generate access tokens, connect your Page if it isn't listed

5. Click Generate on the Page row → tick the acknowledgement → Copy

The token is shown only once. It never expires (expires_at: 0 in the Access Token Debugger) unless you revoke it or lose the admin role.

Do not generate this from business.facebook.com → System Users — that produces a System User token, which the inbox rejects. See the section above.

Verify what you got:

curl -s "https://graph.facebook.com/v25.0/debug_token?input_token=$TOKEN&access_token=$TOKEN"

You want "type": "PAGE", "expires_at": 0, and a user_id that is your personal profile — not a System User.

Instagram Direct: requesting Advanced Access

Reading Instagram DMs from people who have no role on your app requires Advanced Access to instagram_manage_messages, which only App Review grants. In your app → Use cases → the Instagram or Messenger use case → Permissions and features → the permission row → Actions → Add to app review. Expect to supply a working prototype and a screencast.

Nothing else in this server depends on it.

Safety notes

Six tools write to the outside world. send_message and private_reply message a real person; create_comment, reply_to_comment and update_comment publish publicly under the Page's name; delete_comment is irreversible. They are annotated (readOnlyHint / destructiveHint) so MCP clients can gate them, but you should still confirm the recipient and the exact text with a human before firing them.

hide_comment is the reversible alternative to delete_comment for moderation.

License

MIT