Skip to main content
Glama
io.github.mohammad-abbasi-sh/bonbama-mcp

io.github.mohammad-abbasi-sh/bonbama-mcp

bonbama-mcp 🇮🇷

mcp-name: io.github.mohammad-abbasi-sh/bonbama-mcp

Unofficial read-only MCP server for bonbama.ir — Gorgan's discount platform: local businesses, discount codes and campaigns, business categories, and magazine articles. All data is read live from bonbama.ir public pages at call time — nothing is hardcoded.

Not affiliated with Bonbama. Built for the Bazaar MCP Hub submission — see DEPLOY.md for hosting.

For AI agents

Local (stdio) — add to your MCP client config:

{
  "mcpServers": {
    "bonbama": {
      "command": "uvx",
      "args": ["bonbama-mcp"]
    }
  }
}

Or run locally: python -m bonbama_mcp.server (needs mcp<2, httpx, uvicorn).

Hosted (streamable HTTP) — for clients that connect to a remote MCP server:

https://api.bonbama.ir/mcp

MCP endpoint is /mcp (streamable HTTP, stateless — no session affinity needed); liveness probe at /health. Hosting guide: DEPLOY.md.

Related MCP server: PrijsProfeet MCP

Tools

Tool

Description

bb_search_businesses

Search businesses by keyword and/or category slug — query, category, limit

bb_get_business

Full details for one business — slug (e.g. testino, takchh): description, city, address, rating, category, ACTIVE campaigns with discount + expiry, and any literal discount codes published on the page

bb_list_categories

All business categories with Persian names + business/campaign counts

bb_search_discounts

Search ACTIVE discount campaigns site-wide — query (empty = popular campaigns)

bb_search_articles

Search the Bonbama magazine (guides, best-of-Gorgan lists) — query

bb_health

Check whether bonbama.ir is reachable right now

Example output (bb_get_business / takchh, trimmed):

{"name": "طاقچه | خرید کتاب الکترونیکی و صوتی و اشتراک بی‌نهایت",
 "city": "تهران", "campaign_count": 5,
 "campaigns": [{"title": "۵۰٪ تخفیف اولین خرید طاقچه — فقط از طریق بن‌باما",
   "discount": "50%", "valid_through": "2027-01-20"}],
 "codes": [{"code": "OFF50", "note": "۵۰٪ تخفیف اولین خرید"}]}

Notes:

  • Campaigns, codes, prices and expiries are read live from the page on every call — they change; always report fetched_at and tell the user to verify on the business page before buying.

  • Literal codes (e.g. OFF50) come from the business page's own text. Some campaigns instead need the user to press «دریافت کد» on bonbama.ir (free, needs a free account) to generate their personal code/QR — those codes are per-user and are never returned here.

  • Data sources: bonbama.ir sitemaps + public search, business, category and article pages — no key, no login, read-only. This server never writes anything to bonbama.ir.

Development

python -m venv .venv && .venv/bin/pip install -e . pytest
.venv/bin/python -m pytest tests/ -q          # 29 offline + 7 live tests
.venv/bin/python -m pytest tests/test_bonbama.py -q   # offline only

Cite this project

If you use bonbama-mcp, build on it, or write about it, please credit the source:

Abbasi, Mohammad. bonbama-mcp. v0.1.0, 2026. https://github.com/mohammad-abbasi-sh/bonbama-mcp

A ready-to-copy citation is also available from GitHub's Cite this repository button (see CITATION.cff). Commercial use needs a separate license (see below).

License

PolyForm Noncommercial 1.0.0 — free for personal and non-commercial use; commercial use needs a separate license.

Built by Mohammad Abbasi — Almanibama · mabbasi.ir

Available Tools

6 tools
bb_get_businessA

Full details for one business: name, description, city, address, rating, category, ACTIVE campaigns (title, discount, expiry — read live from the page) and any literal discount codes published on the page. slug: e.g. "testino", "takchh" (from bb_search_businesses).

Inputs: slug (required). Returns: result

bb_healthA

Check whether bonbama.ir is reachable right now.

Returns status ok (HTTP 200), blocked (HTTP 403/429 — bot wall or rate limit) or error, plus the HTTP status and the probed URL. One polite request; it does not fetch any listings.

Inputs: no named parameters. Returns: result

bb_list_categoriesA

All Bonbama business categories with Persian names and (where the homepage publishes them) business/campaign counts. Use the slug with bb_search_businesses(category=...).

Inputs: no named parameters. Returns: result

bb_search_articlesA

Search the Bonbama magazine (buying guides, discount explainers, best-of-Gorgan lists). query: Persian/English keyword. Matches article titles on the latest index pages and URL slugs.

Inputs: query (required), limit. Returns: result

bb_search_businessesA

Search Bonbama businesses by keyword and/or category.

query: Persian/English keyword (e.g. "ناخن", "testino"). category: a category slug from bb_list_categories (e.g. "zban", "rstoran"). Give at least one of query/category. Returns name, URL, slug and active-campaign count per business.

Inputs: limit, query, category. Returns: result

bb_search_discountsA

Search ACTIVE discount campaigns site-wide by keyword (e.g. "کفش", "شهربازی"). With no query, returns current popular campaigns. Each result: business, campaign title, discount, Jalali expiry, campaign URL and how many codes were sent.

Inputs: limit, query. Returns: result

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    A4.1/5.0

    Scored across 6 tools

    Disambiguation5/5

    Each tool targets a distinct entity and action: business search vs. single-business detail vs. category listing vs. discount search vs. article search vs. health probe. The inclusion of the category-listing tool explicitly feeding the search tool's category parameter further separates the roles. No two tools could be reasonably confused for one another.

    Naming Consistency4/5

    A consistent bb_ prefix plus verb_noun pattern (search_businesses, get_business, list_categories, search_discounts, search_articles) is applied throughout. The only deviation is bb_health, a bare noun rather than a verb_noun form, but it is still predictable and readable.

    Tool Count5/5

    Six tools is a tight, well-scoped surface for a site-search server covering two content types (businesses, discounts) plus articles and categories. Every tool earns its place, with no redundant or filler operations.

    Completeness4/5

    The lifecycle is largely covered: discover categories, search businesses, fetch business detail (including its campaigns), search discounts, search articles, and verify reachability. Minor gaps exist — there is no direct single-campaign or single-article fetch, and no explicit city filter — but campaign and article data surface through the search and detail responses, so agents can work around it.

    Maintenance

    ActivityMaintained
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers

    • F
      license
      C
      quality
      B
      maintenance
      Enables AI clients to search, fetch and cross-compare products, prices, sellers, offers, availability and specifications between Digikala and SnappShop, with tools for finding the best price or best-value offer using explicit filters and explainable reasoning. It also supports remote Streamable HTTP deployment so the same capabilities can be registered as a custom connector in clients such as Grok.
      11
      -
    • A
      license
      A
      quality
      C
      maintenance
      Enables querying live offers and prices from 10 Dutch supermarket chains through a single normalised JSON API. Exposes 26 curated tools, including product search and category lookups, over stdio or authenticated Streamable HTTP.
      20
      1
      MIT
    • A
      license
      A
      quality
      B
      maintenance
      Enables AI agents to search Snappfood restaurants and SnappMarket stores across Iran, compare true order costs including packaging and delivery, read menus, minimum orders, ETAs and reviews, and surface live flash deals. All operations are read-only, with no login, basket, ordering or payment access.
      8
      21
      725 PyPI
      40
      PolyForm Noncommercial 1.0.0
    • A
      license
      Not graded
      quality
      B
      maintenance
      Enables AI agents to search Jabama stays, group tours, events and theater seats, and to fetch the exact night-by-night price for given dates and guests along with calendars, house rules, amenities, host reputation and reviews. Runs locally as a read-only server with no login, booking or payment.
      145 PyPI
      2
      PolyForm Noncommercial 1.0.0