bama-mcp: bama.ir MCP server for AI agents

Let your AI agent search the Iranian car market (باما).

An unofficial, read-only MCP server for bama.ir, Iran's biggest car marketplace: search ads by brand, model, city and price, read full ad details, compare prices in Toman, and browse every brand, model and city — all from Claude, Cursor or Copilot.

For AI agents

• What: unofficial MCP server for bama.ir (باما), the Iranian car marketplace. Persian and Finglish queries work; prices in Toman.
• Install: claude mcp add bama -- uvx bama-mcp (stdio, needs uv and Python 3.10+). Snippets for Claude Desktop, Cursor, VS Code and Hermes below.
• Auth: none. No API key or account.
• Access: read-only. No login, no ads posted, nothing is bought or changed.
• Tools: 5: search_cars, car_details, list_brands, list_models, list_cities. Typical sequence: list_brands -> list_models -> search_cars -> car_details.
• Use when: the user wants Iranian car ads, prices, comparisons, or "is my car worth X" checks.
• Do not use when: the user wants to sell/post a car, needs their bama.ir account, or is outside Iran with a VPN on (bama.ir drops foreign IPs at TLS level).
• Output: compact JSON. Each item carries summary_fa (ready Persian one-liner for tables) and price_fa (۴۱۰ میلیون تومان). price_toman is an int or null (negotiable ads are never 0). Ad code and url pass between tools.

Quick start

The server runs over stdio as uvx bama-mcp (needs uv and Python 3.10+; use the full path to uvx from which uvx if your client cannot find it).

Claude Code

claude mcp add bama -- uvx bama-mcp

Claude Desktop

Settings → Developer → Edit Config, then add:

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

Cursor

Add the same JSON block to ~/.cursor/mcp.json (or .cursor/mcp.json inside a project), or click the button below:

In the terminal:

cursor --add-mcp bama -- uvx bama-mcp

VS Code (Copilot agent mode)

Add to .vscode/mcp.json:

{
  "servers": {
    "bama": { "type": "stdio", "command": "uvx", "args": ["bama-mcp"] }
  }
}

Hermes

hermes mcp add bama --command uvx --args bama-mcp

Anything else

It is a standard stdio MCP server: run uvx bama-mcp, or pip install bama-mcp and run bama-mcp.

Then just ask:

• "پژو ۲۰۶ زیر ۱.۵ میلیارد تو تهران چی هست؟"
• "ارزان‌ترین پژوهای باما رو جدول بکش"
• "جزئیات این آگهی باما رو بده: https://bama.ir/car/detail-…"
• "بین سمند و دنا کدوم ارزون‌تره؟"

What it can do

• 🔎 Search car ads by brand/model, city (all Iranian provinces and cities), price range and sort order
• 💸 True prices in Persian: price_fa (۲۸۰ میلیون تومان, ۴.۱ میلیارد تومان, توافقی) plus summary_fa one-liners ready for tables
• 🧹 Clean results: duplicate ads removed, حواله (installment-slip) ads dropped by default, negotiable ads sink when sorting by price
• 🏙️ Every city in Iran, by Persian or English name
• 🔒 Read-only by design: no account, no posting, no contact — the agent finds, you decide

Tools

Good to know

• Prices are in Toman. price_toman is an integer; price_fa is the human-readable Persian form. A negotiable ad shows توافقی, never 0.
• حواله ads are dropped by default (include_havaleh=false): their price is a down-payment slip, not the car. Pass include_havaleh=true to keep them.
• City names match Farsi or English (تهران, مشهد, tehran). A province name returns the whole province (تهران includes ورامین and پاکدشت).
• bama.ir blocks foreign IPs. Run it from an Iranian IP with the VPN off; otherwise the TLS handshake is dropped and the tool answers a clear bama_timeout error. BAMA_MCP_PROXY sets an HTTP proxy that exits in Iran.
• page_size max is 30 — bama's API rejects larger pages.
• One call is usually enough. search_cars walks up to max_pages pages (default 10 = 300 ads, cap 20) and returns the combined, de-duplicated list, so the agent does not need to page by hand. With sort=4 (cheapest) plus price_max — or sort=3 plus price_min — it stops as soon as the sorted list passes the bound, which makes the bounded result complete rather than truncated. If truncated is true, continue with page = page + pages_fetched.

FAQ

Is it official, safe and free? It is unofficial, open source (MIT) and free. It is read-only, needs no account or API key, and runs on your machine with no hosted server in between.

It times out / errors immediately. bama.ir drops foreign IPs at the TLS level. Turn the VPN off, or set BAMA_MCP_PROXY to a proxy that exits in Iran.

The model filter returns brand-level results. Known limitation (v0.1): vehicle=peugeot,207 currently behaves like vehicle=peugeot — bama expects a different value format. Brand search is exact. City and price filters work.

car_details says pass the full URL. Correct: pass the url field from search_cars, not the ad code alone.

What are summary_fa and price_fa for? Ready-made Persian strings so the agent can render a table or sentence without reformatting numbers.

فارسی: سرور MCP باما

سرور bama-mcp یک ابزار غیررسمی و فقط‌خواندنی برای باما (bama.ir) است. به دستیار هوش مصنوعی شما (Claude، Cursor، Copilot و ...) اجازه می‌دهد آگهی‌های خودرو را بر اساس برند، مدل، شهر و قیمت جستجو کند، جزئیات کامل هر آگهی را بخواند و همه برندها و شهرهای ایران را ببیند.

• فقط خواندنی است: وارد حساب نمی‌شوید، آگهی ثبت نمی‌شود و هیچ چیزی خرید یا تغییر داده نمی‌شود.
• قیمت‌ها به تومان است و به صورت فارسی (۲۸۰ میلیون تومان) نمایش داده می‌شود.
• روی سیستم خود شما اجرا می‌شود و به هیچ سرور واسطی داده نمی‌فرستد.

نصب در Claude Code:

claude mcp add bama -- uvx bama-mcp

برای Claude Desktop، Cursor، VS Code و Hermes هم نمونه تنظیمات در بالای همین صفحه (بخش Quick start) آمده است.

بعد بپرسید: «پژو ۲۰۶ زیر ۱.۵ میلیارد تو تهران چی هست؟»

نکته: سرور باید روی سیستمی با IP ایران و بدون VPN اجرا شود، چون باما درخواست‌های خارجی را در سطح TLS مسدود می‌کند.

Development

git clone https://github.com/Amrzas/bama-mcp && cd bama-mcp
uv sync --group dev
uv run pytest                # offline, against recorded responses
uv run pytest -m live        # real bama.ir API (needs an Iranian IP)
uv run ruff check src tests

Tools live in src/bama_mcp/ (server.py, pure helpers in format.py, catalog lookups in catalog.py, shared client in http.py). Issues and PRs are welcome, especially new tools and fixes for API changes.

Releases: bump the version in pyproject.toml and server.json, then push a v* tag. GitHub Actions tests, publishes to PyPI and creates the GitHub Release.

Disclaimer

Unofficial; not affiliated with Bama. Read-only access to the data of public pages. Keep request rates low. If this saves you clicks, a star helps others find it.

License

MIT