Repository avatar
Other Tools
v0.1.0
active

bonbama-mcp

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

Unofficial read-only MCP server for bonbama.ir — Gorgan discounts, businesses and codes.

Documentation

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.

Tools

ToolDescription
bb_search_businessesSearch businesses by keyword and/or category slug — query, category, limit
bb_get_businessFull 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_categoriesAll business categories with Persian names + business/campaign counts
bb_search_discountsSearch ACTIVE discount campaigns site-wide — query (empty = popular campaigns)
bb_search_articlesSearch the Bonbama magazine (guides, best-of-Gorgan lists) — query
bb_healthCheck 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