
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
| 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_atand 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
bonbama-mcppip install bonbama-mcpRelated Servers
io.github.mohammad-abbasi-sh/arabam-mcp
Unofficial read-only MCP server for arabam.com used-car listings: search, details, price stats.
io.github.mohammad-abbasi-sh/armut-mcp
Unofficial read-only MCP server for armut.com local services: search, pros, FAQs, price guides.
io.github.mohammad-abbasi-sh/autobahn-mcp
Unofficial read-only MCP server for the German Autobahn — roadworks, closures, warnings & charging.