pelando-mcp

MCP server for pelando.com.br, the Brazilian community deal board. It answers the question a price comparator structurally cannot: did the crowd believe this discount?

Pelando's temperature score goes negative when users judge a deal fake or the price inflated before the "promotion". No other Brazilian price source exposes that, and — as of August 2026 — no other MCP server exposes Pelando at all.

See PLAN.md for the full design, the reconnaissance behind it, and the source-selection decision.

What it is, and what it is not

This is a community deal reader, not a price comparator. Pelando has no product catalogue — verified four ways, see PLAN.md §2 — so the server does not pretend otherwise:

It can tell you	It cannot tell you
What users posted, at what price, from which store	What a product costs on a shelf right now
Whether the crowd upvoted or downvoted it	Every store selling product X, with prices
What the comment thread says is wrong with it	A 30/90-day price curve
Coupon codes and which store has active deals	Product specs, or anything about a product nobody posted

Coverage is exactly what the community posts. Even mainstream terms legitimately return nothing: iphone 16 pro currently has zero live promotions against ~99 archived ones. That is a real answer, not a failure.

Tools

Tool	Purpose
search_deals	Free-text deal search. Weak matches are demoted to related, not hidden.
browse_feed	Pelando's own feeds, optionally scoped to a community (tech-lover for electronics).
get_deal	One deal by UUID or slug — a pasted /d/<slug> URL works directly.
get_deal_comments	The comment thread, where a bad posting gets corrected.
assess_deal_quality	The point of the project. The crowd's verdict, with its evidence.
search_stores	Merchant lookup: live promotion counts and top coupons.
get_store_coupons	Literal redeemable codes, with prose masquerading as codes filtered out.
list_communities	The 11 communities — the site's only taxonomy.
ping	Liveness.

assess_deal_quality

Every signal is already in payloads we fetch, so it costs at most one extra request. Real output, against a live deal:

{
  "title": "[REEMBALADO] GeForce RTX 5070 OC 12GB",
  "verdict": "crowd_rejected",
  "temperature": -229,
  "price": 4129.0,
  "store_name": "Terabyte",
  "warnings": [
    "Negative temperature (-229). On Pelando that usually means users judged the discount fake,
     the price inflated beforehand, or the listing misleading.",
    "The title declares this as 'reembalado'. Do not compare it against new-unit prices."
  ]
}

It returns a verdict with its evidence attached, never a bare score. A score invites the calling model to quote it as fact; evidence invites it to explain, and lets you disagree.

Quick start (local, venv)

Requires Python ≥ 3.12.

python3 -m venv venv
./venv/bin/pip install -e ".[dev]"
./venv/bin/pytest -m "not live"     # offline, runs against checked-in fixtures
./venv/bin/pelando-mcp              # runs the MCP server over stdio

End-to-end check against the live site:

./venv/bin/python scripts/verify_all_tools.py     # writes to data/verify/

Docker

Multi-arch images (linux/amd64, linux/arm64) are published on every push to main:

docker pull ghcr.io/gabrielbelli/pelando-mcp:latest
docker run --rm -i -v pelando-mcp-data:/data ghcr.io/gabrielbelli/pelando-mcp:latest

Or build locally:

docker compose build
docker compose run --rm pelando-mcp

A named volume holds the sqlite cache at /data/cache.sqlite.

Run this from home, not from a cloud host. Cloudflare fronts Pelando and blocks datacentre IP ranges outright — a 403 interstitial on every request, robots.txt included, no matter how honest the User-Agent is. Measured: the identical client returns 200 from a residential connection and 403 from a GitHub Actions runner. So the image is fine on a laptop, home server or NAS, and will not work on a VPS. Treat that as a constraint to respect rather than a puzzle to route around with a proxy — see Politeness.

Wiring into Claude

Docker (recommended)

{
  "mcpServers": {
    "pelando": {
      "command": "docker",
      "args": ["run", "--rm", "-i", "-v", "pelando-mcp-data:/data", "ghcr.io/gabrielbelli/pelando-mcp:latest"]
    }
  }
}

Local venv

{
  "mcpServers": {
    "pelando": {
      "command": "/absolute/path/to/pelando-mcp/venv/bin/pelando-mcp"
    }
  }
}

Configuration

Variable	Default	Purpose
PELANDO_USER_AGENT	pelando-mcp/0.1 (+repo url)	Sent on every request. See below.
PELANDO_RATE_LIMIT_RPS	1.0	Max requests/sec.
PELANDO_RATE_LIMIT_BURST	3	Token-bucket burst.
PELANDO_CACHE_PATH	/data/cache.sqlite (Docker) / data/cache.sqlite (local)	sqlite cache.
PELANDO_LOG_LEVEL	INFO	structlog level.

Politeness, and why Pelando

Pelando was chosen on compliance grounds as much as data grounds. Zoom, Buscapé, Bondfaro, Mercado Livre and Hardmob all name ClaudeBot / Claude-User / Anthropic-AI under Disallow: / — Zoom's under a heading reading "Bloqueio de Scrapers de Inteligência Artificial (Proteção do catálogo e dados de preço)". Pelando's robots.txt is Allow: /, with disallows confined to logged-in pages, and its Terms of Use carry no anti-crawler clause.

Practically, that means:

• The User-Agent identifies us truthfully rather than impersonating Chrome. Cloudflare blocks bot UA strings — including python-httpx, our own library — but an honest self-identifying UA returns 200. If this server ever becomes a nuisance, the operator can email us instead of blocking us. Don't replace it with a browser string.
• Cloudflare also blocks by IP range, not only by UA. Datacentre ranges get a 403 interstitial however honest the UA is, which is why this runs from a home connection and why the live contract tests are not in CI. A residential proxy would defeat that block; we don't ship one.
• 1 req/s, concurrency 1, with aggressive sqlite caching. Measured headroom is much larger; that is not a reason to use it.
• robots.txt is fetched at startup and paths are actually evaluated against it.
• The merchant's own link is surfaced, never Pelando's affiliate redirect. A tool that presents itself as neutral should not silently monetise your click for a third party.
• No login, no writes, no background polling, no bulk crawling.

Layout

src/pelando_mcp/
├── server.py        # MCPServer entry, registers tools
├── client.py        # httpx async, honest UA, token bucket, retries, robots, cache
├── api.py           # typed calls; validates params the API would silently ignore
├── models.py        # pydantic v2 — nullability mirrors observed live payloads
├── normalise.py     # condition detection + relevance filtering
├── quality.py       # the crowd-verdict heuristic
└── tools/           # MCP tool registrations
tests/
└── fixtures/        # real captured JSON + HTML for offline parser tests
scripts/
└── verify_all_tools.py

Notes

• Data comes from an undocumented internal JSON API. It has no contract and no deprecation policy, so pytest -m live hits the real endpoints and fails on schema drift. A scraper does not break loudly — it starts returning "no deals found" and lies to you. Run it by hand every so often, from home; if the edge blocks the network it skips rather than fails, because a 403 says nothing about the schema.
• Deal status is maintained by users and moderators, not verified against the merchant. An "active" deal can be long dead at the shop.
• Titles are free text. [REEMBALADO], usado and open box are detected and flagged; a silent title is reported as unknown condition, never as new.
• Prices are BRL, exclude frete unless free_shipping is true, and 0 is a real price (free games).

Licence

BSD 2-Clause — see LICENSE.