facebook-mcp

# Facebook MCP Server

<!-- mcp-name: com.hasdata/facebook -->

A hosted Model Context Protocol (MCP) server that gives Claude, Cursor, Windsurf and any other MCP client one read-only Facebook tool. Look up a public page or profile by its handle and get the page record with its exact like count, contact details and owner, plus the post feed with reactions, comments and shares, all as structured JSON, with no Meta developer app and nothing to host.

It reads public Facebook pages that a signed-out visitor can see. Groups and private personal accounts are out of scope.

**1,000 free credits every month, no card required**, which is 100 Facebook calls at the 10-credit rate.

```
https://mcp.hasdata.com/api/mcp?apis=facebook
```

[![Glama score](https://glama.ai/mcp/servers/HasData/facebook-mcp/badges/score.svg)](https://glama.ai/mcp/servers/HasData/facebook-mcp)
[![tool contract](https://github.com/HasData/facebook-mcp/actions/workflows/contract.yml/badge.svg)](https://github.com/HasData/facebook-mcp/actions/workflows/contract.yml)
[![MCP](https://img.shields.io/badge/MCP-remote%20%7C%20streamable%20HTTP-6366f1?style=flat-square)](https://mcp.hasdata.com/api/mcp?apis=facebook)
[![Tools](https://img.shields.io/badge/tools-1-10b981?style=flat-square)](#tools)
[![npm](https://img.shields.io/npm/v/@hasdata/facebook-mcp?style=flat-square&logo=npm&label=npm&color=cb3837)](https://www.npmjs.com/package/@hasdata/facebook-mcp)
[![PyPI](https://img.shields.io/pypi/v/hasdata-facebook-mcp?style=flat-square&logo=pypi&logoColor=white&label=PyPI&color=3775a9)](https://pypi.org/project/hasdata-facebook-mcp/)
[![License](https://img.shields.io/badge/license-MIT-blue?style=flat-square)](LICENSE)

## Contents

- [What you need](#what-you-need)
- [Quick start](#quick-start)
- [Example prompts](#example-prompts)
- [Tools](#tools)
- [Errors and failure paths](#errors-and-failure-paths)
- [Pricing, free tier and limits](#pricing-free-tier-and-limits)
- [How it compares](#how-it-compares)
- [FAQ](#faq)
- [HasData links](#hasdata-links)
- [Development](#development)
- [Contributing](#contributing)
- [License](#license)

## What you need

An MCP client and a HasData API key from the [dashboard](https://app.hasdata.com/sign-up?utm_source=github&utm_medium=syndication&utm_campaign=facebook-mcp), free to create with no card, and the free tier covers about 100 calls a month at the 10-credit rate. This is a remote server, so the simplest path is a URL and an `x-api-key` header, with no container to run. A client that only speaks stdio reaches it through a thin launcher, published as `@hasdata/facebook-mcp` on npm and `hasdata-facebook-mcp` on PyPI, shown below.

## Quick start

The server URL is the same for every client. We run it hands-on in Claude Code and Claude Desktop. The other blocks follow each client's own documented format for a remote server.

| Field | Value |
| :--- | :--- |
| URL | `https://mcp.hasdata.com/api/mcp?apis=facebook` |
| Transport | HTTP, streamable |
| Auth header | `x-api-key: HASDATA_API_KEY` |

Clients with OAuth support can add the same URL as a connector and sign in without putting a key in a config file.

<details>
<summary><b>Claude Code</b></summary>

```bash
claude mcp add --transport http facebook "https://mcp.hasdata.com/api/mcp?apis=facebook" \
  --header "x-api-key: HASDATA_API_KEY"
```

</details>

<details>
<summary><b>Claude Desktop</b></summary>

Settings, then Connectors, then Add custom connector, then paste `https://mcp.hasdata.com/api/mcp?apis=facebook` and sign in.

For the config-file route, Claude Desktop loads only local (stdio) servers, so it reaches a remote server through a stdio launcher. The `@hasdata/facebook-mcp` package is that launcher, and it reads the key from the environment. Add this to `claude_desktop_config.json`:

```json
{
  "mcpServers": {
    "facebook": {
      "command": "npx",
      "args": ["-y", "@hasdata/facebook-mcp"],
      "env": { "HASDATA_API_KEY": "YOUR_KEY" }
    }
  }
}
```

For Python instead of Node, swap the launcher for the PyPI package, which `uvx` runs without a manual install:

```json
{
  "mcpServers": {
    "facebook": {
      "command": "uvx",
      "args": ["hasdata-facebook-mcp"],
      "env": { "HASDATA_API_KEY": "YOUR_KEY" }
    }
  }
}
```

</details>

<details>
<summary><b>Cursor</b></summary>

`~/.cursor/mcp.json` for every project, or `.cursor/mcp.json` for one:

```json
{
  "mcpServers": {
    "facebook": {
      "url": "https://mcp.hasdata.com/api/mcp?apis=facebook",
      "headers": { "x-api-key": "HASDATA_API_KEY" }
    }
  }
}
```

</details>

<details>
<summary><b>Windsurf</b></summary>

`~/.codeium/windsurf/mcp_config.json`. Windsurf calls the field `serverUrl`, not `url`:

```json
{
  "mcpServers": {
    "facebook": {
      "serverUrl": "https://mcp.hasdata.com/api/mcp?apis=facebook",
      "headers": { "x-api-key": "HASDATA_API_KEY" }
    }
  }
}
```

</details>

<details>
<summary><b>VS Code</b></summary>

`.vscode/mcp.json` in the workspace:

```json
{
  "servers": {
    "facebook": {
      "type": "http",
      "url": "https://mcp.hasdata.com/api/mcp?apis=facebook",
      "headers": { "x-api-key": "HASDATA_API_KEY" }
    }
  }
}
```

</details>

## Example prompts

- How many people like the Nike page, and how many are talking about it this week?
- Pull the contact details and the confirmed owner of this Facebook page.
- Read the last ten posts on this page and tell me which got the most shares.
- Compare the reaction mix on this brand's posts with its competitor's.
- Is this Facebook page verified, and what category does it list?
- Walk this page's feed back to the start of the month and list the posts with video.

One call returns the page record and the newest post. Walking the feed takes one more call per three posts, using the token the previous response returns.

## Tools

One tool, 10 credits per successful call.

### Get Facebook profile

[`hasdata_facebook_profile_getFacebookProfile`](https://docs.hasdata.com/apis/facebook/profile?utm_source=github&utm_medium=syndication&utm_campaign=facebook-mcp)

A public page or profile, with its feed.

| Tool | Credits | What it returns |
| :--- | :--- | :--- |
| `hasdata_facebook_profile_getFacebookProfile` | 10 | The page record with likes, followers, contact details and owner, the newest post, the photo strip, and a token for the next three posts |

| Parameter | Type | Required | Notes |
| :--- | :--- | :--- | :--- |
| `handle` | string | yes | The username, with or without `@`, or the numeric id from a `profile.php?id=…` URL |
| `language` | string | | Language the page is rendered in, one of 32 codes such as `en`, `de`, `pt` or `zh-hans` |
| `nextPageToken` | string | | Cursor from the previous response, to read the next three posts |

The first call returns four blocks. `profile` is the page record, `posts` holds the newest post, `photos` is the strip of recent images, and `pagination` carries `postsPerPage`, `nextPage` and the `nextPageToken` to continue with.

Every call made with a token returns `posts` and `pagination` only, three posts at a time, with a fresh token until the feed ends and the token disappears.

```json
{
  "profile": {
    "id": "100044541544829",
    "pageId": "15087023444",
    "name": "Nike",
    "username": "nike",
    "url": "https://www.facebook.com/nike",
    "category": "Sportswear Store",
    "biography": "Just Do It.",
    "likesCount": 39545204,
    "talkingAboutCount": 173971,
    "checkInsCount": 18299,
    "followersCount": "39M followers",
    "followingCount": "24 following",
    "verified": true,
    "website": "nike.com",
    "websiteUrl": "http://nike.com/",
    "phone": "+48 58 881 27 61",
    "owner": { "name": "NIKE, Inc.", "isConfirmed": true },
    "profilePicUrl": "https://scontent.fmex5-1.fna.fbcdn.net/v/t39.30808-1/284964043_10159903868513445_7696353984967674128_n.jpg",
    "coverPhotoUrl": "https://scontent.fmex25-1.fna.fbcdn.net/v/t39.30808-6/285211224_10159903868008445_5477337468887983165_n.png"
  },
  "posts": [
    {
      "id": "1393461115481927",
      "url": "https://www.facebook.com/reel/2166091230582141/",
      "text": "Leave your limits at the surface. #JustDoIt",
      "hashtags": ["#JustDoIt"],
      "timestamp": "2025-09-15T16:01:59.000Z",
      "reactionsCount": 7885,
      "commentsCount": 2461,
      "sharesCount": 1124,
      "reactions": [{ "type": "Like", "count": 6491 }],
      "media": [{ "id": "2166091230582141", "type": "Video" }]
    }
  ],
  "photos": [{ "id": "1095811278580247", "type": "Photo", "image": "https://scontent.fmex22-1.fna.fbcdn.net/v/t39.30808-6/471313661_18515827156020081_2460706748949541958_n.jpg" }],
  "pagination": { "postsPerPage": 3, "nextPage": 2, "nextPageToken": "eyJjdXJzb3IiOiJDZzhPYjNKbllXNXBZMTlqZFhKemIzS…" }
}
```

## Errors and failure paths

Plan for these rather than assuming a happy path.

**Three of the counts are numbers and two are strings, and that is not a bug.** `likesCount`, `talkingAboutCount` and `checkInsCount` are the exact figures Facebook publishes. `followersCount` and `followingCount` arrive as the rounded, localised text the page shows, `"39M followers"` in English and `"39 Mio. Follower"` when `language` is `de`. Compare with the numbers, display the strings.

**`language` changes the strings, not the numbers.** `category` moved from `Sportswear Store` to `Sportbekleidungsgeschäft` under `de`, while `likesCount` stayed a number. Pick the language for the reader, not for the maths.

**A page that does not exist, was deleted or is not public still answers 200.** The response then carries `error` instead of `profile`, and the call is billed. Test for `profile` before you read it. Groups and private personal accounts land here too.

**The first page of the feed holds one post, not three.** `postsPerPage` says 3, and pages two onward do return three, but the opening response carries the newest post alone alongside the profile and photos. Count what you got ra