Facebook Marketplace MCP Server
Provides tools to search Facebook Marketplace listings by query, location, and filters, and to retrieve detailed listing metadata such as description, price, seller information, attributes, photos, and videos.
This server does not currently have a deployable release on Glama. Follow the repository's setup instructions to install and configure it for your MCP client, including any required credentials and local dependencies.
Facebook Marketplace MCP Server
An MCP (Model Context Protocol) server that lets any AI tool — Claude, Cursor, VS Code, Claude Code, etc. — search Facebook Marketplace.
It does not automate a browser. It replays Facebook's own internal GraphQL
protocol (the same POST /api/graphql/ requests the website makes) using the
open-source facebook-gql-scraper
engine, and can route every request through Geonode proxies to avoid IP
bans and rate limits.
Built on existing work rather than from scratch: the scraping engine is
facebook-gql-scraper(MIT), which already handles doc-id auto-rediscovery, pagination, and full listing metadata. This project only wraps it in an MCP interface and adds Geonode proxy wiring.
How it works
AI tool (Claude / Cursor / ...)
│ MCP (stdio JSON-RPC)
▼
server.py ── search_marketplace / get_listing / status
│
▼
facebook-gql-scraper (GraphQL, no browser)
│ requests via Geonode proxy (optional)
▼
Facebook GraphQL API (your session cookies for auth)Related MCP server: Marketplace Finder MCP Server
Prerequisites
Python 3.10+ (tested on 3.12)
A Facebook account (used to export session cookies — never stored in code)
Optional: a Geonode Proxies plan (residential / ISP / rotating datacenter) for IP rotation
Install
git clone https://github.com/Sniffr/facebook-mcp.git
cd facebook-mcp
python3 -m venv .venv
.venv/bin/pip install -r requirements.txtVerify the setup (no network calls to Facebook, just imports + config):
.venv/bin/python server.py --check # config only
.venv/bin/python server.py --check --live # also confirms your saved login worksRun the offline test suite (no Facebook traffic):
.venv/bin/python -m unittest discover -s tests -vGet your Facebook cookies (automatic)
The server authenticates using your Facebook session cookies. The easiest way is to let the helper open Chrome and grab them for you:
.venv/bin/python get_cookies.py
# or: .venv/bin/python server.py --loginA Chrome window opens (your installed Chrome, using a dedicated profile in
.chrome-profile/).Log in to Facebook in that window if prompted.
The script detects the login (
c_usercookie) and auto-saves all facebook.com cookies tofacebook_cookies.json— no copy-paste.
Run it again later and, because the profile is persistent, you'll usually still
be logged in, so it just re-exports instantly. The cookies file is written with
owner-only permissions (600).
Reuse the login in your everyday Chrome
If you're already logged in to Facebook in your normal Chrome (144+), skip the separate profile:
.venv/bin/python get_cookies.py --default-chromeIt opens
chrome://inspect/#remote-debuggingin your Chrome — switch remote debugging on there, and click Allow if Chrome asks.It reads the facebook.com cookies (plus your Chrome's User-Agent) and saves them. If macOS blocks reading Chrome's profile folder, it falls back to port
9222(override withCHROME_DEBUG_PORT).Switch remote debugging back off afterwards — while it's on, any local app can control your browser.
Trade-off: the scraper then shares your everyday session, so if Facebook ever objects to it, you'd be logged out of Chrome too. The dedicated profile keeps those separate.
Both modes also write facebook_cookies.browser.json with the capturing
browser's User-Agent. The server replays requests with that identity (and
matching sec-ch-ua headers), because a session that suddenly appears from a
different OS/browser is a classic trigger for Facebook to log it out.
Manual fallback
If you'd rather not use the browser helper, export cookies yourself:
Cookie-Editor (Firefox/Chrome) — visit facebook.com, open the extension,
Export→JSON, save it asfacebook_cookies.jsonin this folder.EditThisCookie (Chrome) — same idea: export as JSON.
You need at least the c_user and xs cookies from a logged-in session.
Configure Geonode proxies
Geonode proxies are optional but recommended (Facebook rate-limits and flags aggressive scraping; rotating your exit IP helps a lot). In your Geonode dashboard → Proxy configuration, copy your endpoint:
USERNAME— dashboard username (add targeting flags to it, e.g.-country-us)PASSWORD— dashboard passwordHOST— generated endpoint host (IP or DNS)PORT— e.g.9000for rotating HTTP/HTTPS
Set one of these forms:
Env var | Example |
|
|
|
|
The credentials are URL-encoded for you when you use the split form. The full
proxy URL is passed straight through to the engine's proxy= parameter.
Attach it to an AI tool
Point your MCP client at server.py. Example (Claude Code / Claude Desktop /
Cursor — see mcp.example.json):
{
"mcpServers": {
"facebook-marketplace": {
"command": "/path/to/facebook-mcp/.venv/bin/python",
"args": ["/path/to/facebook-mcp/server.py"],
"env": {
"FACEBOOK_COOKIES_FILE": "/path/to/facebook-mcp/facebook_cookies.json",
"GEONODE_PROXY_URL": "http://YOUR_USERNAME:YOUR_PASSWORD@YOUR_HOST:9000"
}
}
}
}Claude Code one-liner (--scope user makes it available in every project):
claude mcp add --scope user facebook-marketplace -- \
/path/to/facebook-mcp/.venv/bin/python \
/path/to/facebook-mcp/server.pyTools
search_marketplace
Search by query, location, and filters.
Param | Type | Default | Description |
| string | — | Search term (required) |
| number |
| Search centre latitude |
| number |
| Search centre longitude |
| int | 50 | Search radius (1–500) |
| number | — | Min price (listing currency) |
| number | — | Max price (listing currency) |
| string | — |
|
| string | — |
|
| int | — | Only listings from the last N days |
| int | 20 | Max results (1–100) |
Returns query, the location searched, count, and listings, each with: id, title, price, currency, strikethrough_price, location,
url, is_live/is_sold/is_pending, category_id, delivery_types,
seller {id, name}, and photos.
get_listing
Full metadata for one listing: description, exact lat/long, attributes, delivery options, seller info + ratings, photos, and videos.
Param | Type | Description |
| string | The numeric listing ID, or a |
authenticate
Re-login when the session is missing or expired — ask your AI tool to "log in
to Facebook" (session errors from the other tools also point it here). It
first checks the saved session and returns already_logged_in if it still
works. Otherwise it opens Chrome, waits for you to log in, saves the new
cookies and browser identity, switches the running server to them, and
confirms with Facebook.
Param | Type | Default | Description |
| string |
|
|
| int | 180 | How long to wait for you to finish logging in |
| bool | false | Capture a new session even if the current one works |
Statuses: logged_in, already_logged_in, waiting (the login window/tab is
open — log in, then call it again), needs_remote_debugging (switch it on at
chrome://inspect/#remote-debugging, then call again), rejected (cookies
saved but Facebook didn't accept them), error.
status
Reports config: engine version, cookie-file presence, whether a proxy is
configured (password masked), and the default location. No network calls
unless you pass verify_session: true, which loads facebook.com once and
reports whether the saved login is still valid.
All tools are marked read-only. Results come back as structured JSON; failures
come back as MCP errors (isError: true) with a message saying what to do,
e.g. re-run get_cookies.py when the session has expired.
Configuration reference
Relative paths are resolved against the project folder, not the MCP client's working directory, so the defaults work no matter where the client starts the server.
Env var | Default | Purpose |
|
| Cookies JSON path |
|
| Cache of discovered GraphQL doc-ids |
| capturing browser's UA | Override the User-Agent (client hints follow it) |
|
| Search centre when the caller gives none |
|
| Per-request HTTP timeout (seconds) |
| — | Preferred ISO code for ambiguous price symbols ( |
| — | Full Geonode proxy URL |
| — | Split proxy credentials |
Troubleshooting
Facebook cookies file not found— export cookies (see above) and pointFACEBOOK_COOKIES_FILEat them.Session expired/logged-out— re-runget_cookies.py; Facebook invalidates sessions frequently. The running server notices the new cookies file automatically, so there's no need to restart your AI tool.First search / first
get_listingis slow (10–30 s) — the engine rediscovers Facebook's rotating GraphQL query IDs by scanning the scripts on a Marketplace page (often 1,000+ bundles; the server fetches them 8 at a time). The IDs are cached infacebook_state.json, so later calls are fast.Searches suddenly return nothing / "doc_id ... was not found" — Facebook rotated its query IDs; the engine rediscovers them on the next call. Retry.
Prices in the wrong currency — Facebook only sends formatted prices (
$25). Ambiguous symbols are read as the most common currency ($→ USD,£→ GBP,¥→ JPY). SetFB_CURRENCY(e.g.CAD) to prefer yours.CAPTCHA / account flag — slow down, and use a Geonode proxy (especially residential) so your real IP isn't burned.
Important legal note
Automating Facebook Marketplace violates Facebook's Terms of Service. Use this for personal, low-volume, read-only research on data you're allowed to access, and at your own risk. The server is read-only — no messaging, listing creation, or other writes.
Credits
facebook-gql-scraper(MIT) — GraphQL scraping engine (0.10.x; the server patches in a currentfb_dtsglookup, parallel bundle prefetching for doc-id discovery, and currency disambiguation)jdcodes1/facebook-marketplace-mcp— reference for MCP tool design (search/get-listing)Geonode — proxy provider
License
MIT. Note that the license covers this code only; it grants no rights under Facebook's Terms of Service (see the legal note above).
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
This server cannot be deployed
Maintenance
Related MCP Connectors
Search Facebook Marketplace, inspect listings and analyze deals. Paid Spottable Pro/Max required.
Facebook & Instagram data for AI agents: pages, posts, groups, ads, Marketplace, profiles, reels.
AI marketplace: search, buy, sell across Amazon, eBay, AliExpress. 13 tools.
Search products in nearby stores. Agents can also list items for sale on a user's behalf.
Related MCP Servers
- AlicenseAqualityAmaintenanceEnables AI assistants to search secondhand marketplaces (Facebook Marketplace, eBay, Depop, Poshmark) for used items with filters like price, condition, size, and color.5286 npm103MIT
- FlicenseNot gradedqualityDmaintenanceEnables AI agents like claude.ai to search online marketplaces (e.g., Facebook Marketplace) through your own logged-in browser, returning structured listings and details.-
- FlicenseAqualityCmaintenanceEnables searching Facebook Marketplace listings from Claude using your existing Facebook session without a browser.72-
- AlicenseAqualityDmaintenanceA focused Model Context Protocol server that enables AI agents to search Facebook Marketplace and retrieve listing details using public GraphQL endpoints, without browser automation or login.34MIT