Skip to main content

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_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

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

Metadata

Release files for bonbama-mcp 0.1.0

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for bonbama-mcp 0.1.0
File Size Uploaded Provenance Actions
bonbama_mcp-0.1.0.tar.gz 42.5 kB With provenance Details for bonbama_mcp-0.1.0.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for bonbama-mcp 0.1.0
File Interpreter ABI Platform Actions
bonbama_mcp-0.1.0-py3-none-any.whl Python 3 none any Details for bonbama_mcp-0.1.0-py3-none-any.whl

Total release size: 59.3 kB

Release files / bonbama_mcp-0.1.0.tar.gz

Download URL bonbama_mcp-0.1.0.tar.gz
Size 42.5 kB
Tags Source
SHA-256 checksum
How to use checksums
2e84a87903f7e2c0e6e2eff268a13533990cd392793bca665be873f0021036a7
BLAKE2b-256 checksum
How to use checksums
f0e26019415348b613e9ea3219fdfd0fe7c71a2a8903b428b9b30452ad2210d5
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 18, 2026.

Transparency log

Release files / bonbama_mcp-0.1.0-py3-none-any.whl

Download URL bonbama_mcp-0.1.0-py3-none-any.whl
Size 16.8 kB
Tags Python 3
SHA-256 checksum
How to use checksums
faf736398e3c6bae26f3730da7b0116ae7fb7017b26d96665ec6057018ebac15
BLAKE2b-256 checksum
How to use checksums
9d74705430b62ee56f3f35dd3b5a731ff2bde2d30efd8a03b6ab4e7d9e66b555
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 18, 2026.

Transparency log

Security for bonbama-mcp 0.1.0

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

Full provenance

Both files in this release have been uploaded with provenance metadata.

Select from 2 files

Attestation for bonbama_mcp-0.1.0.tar.gz

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 18, 2026.

Transparency log

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Release history Release notifications | RSS feed

This release

0.1.0 This release

2 release files Full provenance

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page