io.github.mohammad-abbasi-sh/bonbama-mcp
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@io.github.mohammad-abbasi-sh/bonbama-mcp Show me active discounts on books in Gorgan"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
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/mcpMCP 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 |
| Search businesses by keyword and/or category slug — |
| Full details for one business — |
| All business categories with Persian names + business/campaign counts |
| Search ACTIVE discount campaigns site-wide — |
| Search the Bonbama magazine (guides, best-of-Gorgan lists) — |
| 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 onlyCite 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 toolsbb_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
Scored across 6 tools
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.
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.
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.
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
Related MCP Connectors
Public web data as clean JSON for AI agents: Google, Amazon, TikTok, Instagram, YouTube, LinkedIn, Google Maps, Reddit, Zillow and hundreds more websites. One API key, pay per call, failed calls are free.
Source-cited business facts (phone, address, hours, socials) from any website, worldwide.
OSM-sourced local business data across 9 niches — cuisine, dietary options, delivery, accessibility.
Public web data for AI agents: scrape any page, plus Google, TikTok, Instagram and Amazon as JSON.
Related MCP Servers
- FlicenseCqualityBmaintenanceEnables 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-
- AlicenseAqualityCmaintenanceEnables 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.201MIT
- AlicenseAqualityBmaintenanceEnables 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.821725 PyPI40PolyForm Noncommercial 1.0.0
- AlicenseNot gradedqualityBmaintenanceEnables 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 PyPI2PolyForm Noncommercial 1.0.0