# Balad Maps (pypi · balad-mcp)

Read-only Balad (balad.ir) Iran map: places nearby or on the way, details, reviews, driving routes.

- Trust score: 79/100 (medium)
- Registry status: active
- Liveness: live
- Owner verified: no
- Last scored: 2026-11-05

## Components

- pypi · `balad-mcp`: 79/100 (this document), [markdown](https://verifymcp.io/servers/sepehr071-balad-mcp/balad-mcp.md), [page](https://verifymcp.io/servers/sepehr071-balad-mcp/balad-mcp)

## Channel facts

- Registry: `pypi`
- Package: `balad-mcp`
- Version: `0.1.0`
- Transport: `stdio`

## Trust breakdown

How this component scores in each security and reliability category. Every signal is checked automatically from public evidence about the published package, including repeated runs of it in an isolated sandbox, and we only credit what we can confirm. Scores are 0–100 per category. Scoring method: https://verifymcp.io/docs/scoring (what has changed: https://verifymcp.io/docs/scoring/changelog)

Scored 2026-11-05.

- **Supply Chain Security**: 100/100
  - No malware found by supply-chain analysis.
  - No known CVEs affecting this package version or its production dependencies.
  - Runs hatchling.build at install time, a recognised build step with no custom scripting around it.
  - 1 of 35 dependencies flagged as unhealthy.
- **Provenance & Transparency**: 97/100
  - Source repository is publicly reachable at the declared URL.
  - Cryptographically verified build provenance (signed, bound to sepehr071/balad-mcp).
  - Clear OSI-approved license (MIT).
  - Actively maintained (last published 4 days ago).
  - Disclosure check failed: no security disclosure policy was found in the source repository.
- **Schema Quality & AI Usability**: 64/100
  - AI-judged instruction clarity (excellent).
  - Context-footprint check failed: tool/resource definitions use about 2484 tokens (~276/item across 9 items; 9 tools + 0 resources), over budget; trim descriptions and params.
  - Usage-examples check failed: none of the tools include examples.
- **Stability & Change Management**: 0/100
  - Stability not yet verified: not enough scan history yet (needs a 30-day window).
- **Tool Coverage**: 100/100
  - 100% of tools have a non-trivial description (not blank, and not just the tool's name).
  - 100% of tool parameters carry a description.
- **Tool Safety**: 100/100
  - No prompt-injection markers were found in the server instructions, tool names or descriptions we captured.
  - We read all 9 captured tool definition(s), and no name or description among them implies an irreversible operation.
  - An AI judge read all 10 captured unit(s) of tool text and found none that tries to manipulate the model reading it.
- **Capabilities**: 100/100
  - Implements a current MCP spec version (2026-07-28).

**Unverified: 1 category.** A category scored 0 because we could not verify it: a data source with nothing on this package, evidence we could not reach, or a check we could not run. We only credit what we can confirm.

## Install

### How do I install the Balad Maps MCP server?

Balad Maps runs locally as a PyPI package, launched with uvx balad-mcp. Ready-made configuration for Claude, Cursor, VS Code, Codex and 5 more is on this page, copied from each client's own documentation.

### Claude

```bash
claude mcp add sepehr071-balad-mcp -- uvx balad-mcp
```

### Cursor

```json
{
  "mcpServers": {
    "sepehr071-balad-mcp": {
      "command": "uvx",
      "args": [
        "balad-mcp"
      ]
    }
  }
}
```

### VS Code

```json
{
  "servers": {
    "sepehr071-balad-mcp": {
      "command": "uvx",
      "args": [
        "balad-mcp"
      ]
    }
  }
}
```

### Codex

```bash
codex mcp add sepehr071-balad-mcp -- uvx balad-mcp
```

### opencode

```json
{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "sepehr071-balad-mcp": {
      "type": "local",
      "command": [
        "uvx",
        "balad-mcp"
      ],
      "enabled": true
    }
  }
}
```

### OpenClaw

```bash
openclaw mcp add sepehr071-balad-mcp --command uvx --arg balad-mcp
```

### Hermes

```yaml
mcp_servers:
  sepehr071-balad-mcp:
    command: "uvx"
    args: ["balad-mcp"]
```

### Netclaw

```json
{
  "McpServers": {
    "sepehr071-balad-mcp": {
      "Transport": "stdio",
      "Command": "uvx",
      "Arguments": [
        "balad-mcp"
      ]
    }
  }
}
```

### Vellum

```bash
assistant mcp add sepehr071-balad-mcp -t stdio -c uvx -a balad-mcp
```

### Other

```json
{
  "mcpServers": {
    "sepehr071-balad-mcp": {
      "command": "uvx",
      "args": [
        "balad-mcp"
      ]
    }
  }
}
```

## Changelog

Every change recorded for this component, newest first. Days that predate change tracking, or that we cannot explain, say so: "we were watching and nothing happened" and "we were not watching" are different claims.

### 2026-11-01 (score 79, +15)

- [security improvement] Malware scan: unverified → pass

### 2026-10-31 (score 64)

First indexed and scored.

## MCP tools (9)

### `bl_search` (~270 tokens)

Search places and addresses

Search Balad (Iranian map) for places, streets, neighbourhoods and cities by name, with coordinates and address.

Use it to find a specific place or to turn an address or city name into coordinates (geocoding). Results near
the given point rank first, so pass lat/lng (e.g. a city's coordinates from a first bl_search) when searching
outside Tehran. `type` is poi (a business or landmark: pass its `id` to bl_place), road, city, region or
category; a category row gives a `category` slug for bl_nearby. For every pharmacy, restaurant, etc. around
a point use bl_nearby instead; for coordinates -> address use bl_reverse_geocode. Empty: try a shorter or
Persian query.

Input parameters:

- `lat`: Latitude to search around, e.g. 29.6100. Default: Tehran.
- `limit` (integer): Max results (1-20).
- `lng`: Longitude to search around, e.g. 52.5383. Default: Tehran.
- `query` (string, required): What to find, in Persian or English: a place name, street, address, neighbourhood or city, e.g. برج میلاد or خیابان ولیعصر.

### `bl_nearby` (~402 tokens)

Nearby places by category

List places of one kind (pharmacy, restaurant, gas station...) around a point, with address, phone and rating.

Results are in Balad's own order (as on balad.ir, filters included), each with its straight-line distance
from the point. Text that names a category (پیتزا -> fast-food-restaurant) lists that whole category, as the
site does; `category` then says which. Get the point from bl_search (a city or landmark) or from the user.
For the closest by driving time use bl_nearest_by_drive; for places on the way between two points use
bl_along_route; for hours, photos and reviews of one place call bl_place with its `id`. Empty: widen
radius_km, drop filters or use another word; bl_categories lists valid slugs.

Input parameters:

- `lat` (number, required): Latitude in degrees, e.g. 35.7448.
- `limit` (integer): Max places to return with details (1-40).
- `lng` (number, required): Longitude in degrees, e.g. 51.3753.
- `min_rating`: Only places rated above this, e.g. 4.
- `open_now` (boolean): Only places Balad marks as open right now.
- `price`: Price level; restaurants and cafes only.
- `radius_km` (number): Search box half-width in km, e.g. 1 (0.2-20).
- `sort` (string): relevance (Balad's default), rating (best rated first) or popular (most visited).
- `what` (string, required): A category slug from bl_categories (e.g. pharmacy, restaurant, gas-station, atm) or free text (e.g. پیتزا, کافه).
- `with_phone` (boolean): Only places with a phone number.
- `with_photos` (boolean): Only places with photos.

### `bl_place` (~191 tokens)

Place details

Get one place's full details from Balad: address, phones, hours, open now, rating, amenities, photos, reviews.

\`id` comes from bl_search, bl_nearby, bl_nearest_by_drive or bl_along_route. `hours` maps each weekday
(شنبه..جمعه) to that day's hours as the site shows them; `menu` is the restaurant's menu link when it has one;
\`photos` are full-size image URLs. For more reviews call bl_reviews; for directions call bl_route with its
lat/lng.

Input parameters:

- `id` (string, required): Place id from bl_search or bl_nearby, e.g. 4Dvh6E79N49I2j.
- `photos` (integer): How many photo URLs to include (0-20).
- `reviews` (integer): How many recent reviews to include (0-10).

### `bl_reviews` (~128 tokens)

Place reviews

Get one page of user reviews of a place on Balad, newest first, with stars and the rating breakdown.

\`id` comes from bl_search or bl_nearby. 10 reviews per page; when `more` is true, call again with page+1.
bl_place already includes the first few reviews.

Input parameters:

- `id` (string, required): Place id from bl_search or bl_nearby, e.g. 4Dvh6E79N49I2j.
- `page` (integer): Page number, 10 reviews per page, newest first (1-100).

### `bl_reverse_geocode` (~113 tokens)

Address of a point

Turn coordinates into a Persian street address with city, county and neighbourhood (reverse geocoding).

Use it when the user gives a point or a map pin and wants to know where it is. For the opposite (address or
name -> coordinates) use bl_search. Covers Iran only; elsewhere it answers with an error.

Input parameters:

- `lat` (number, required): Latitude in degrees, e.g. 35.7448.
- `lng` (number, required): Longitude in degrees, e.g. 51.3753.

### `bl_route` (~289 tokens)

Driving route with live traffic

Get driving routes in Iran with distance, travel time in current traffic, tolls, roads and traffic-zone warnings.

Returns up to 3 routes, suggested first, like balad.ir's directions page; `notes` carry the site's labels
(traffic delay, toll in Toman, lowest fuel use); `traffic_plan` appears when the route enters a restricted
zone (طرح ترافیک, زوج و فرد) with its hours. With `stops`, `legs` gives each part. Driving only: Balad's
routing answers car routes for every mode. Get coordinates from bl_search or bl_nearby. Error 'no route': a
point is outside Iran or off the road network.

Input parameters:

- `from_lat` (number, required): Latitude in degrees, e.g. 35.7448.
- `from_lng` (number, required): Longitude in degrees, e.g. 51.3753.
- `steps` (boolean): Include turn-by-turn steps of the suggested route.
- `stops` (array): Stops on the way, in order, each "lat,lng", e.g. ["35.7016,51.4206"] (max 3).
- `to_lat` (number, required): Latitude in degrees, e.g. 35.7448.
- `to_lng` (number, required): Longitude in degrees, e.g. 51.3753.

### `bl_nearest_by_drive` (~266 tokens)

Closest places by driving time

Rank places of one kind around a point by driving time from it in current traffic, quickest first.

Use it for "which pharmacy / gas station / hospital can I reach fastest from here". It takes Balad's top
\`candidates` places of that kind in the box (as bl_nearby lists them) and times a drive to each (one route
call per place). Places Balad cannot route to are left out. For more places without drive times use
bl_nearby; for details of the winner call bl_place.

Input parameters:

- `candidates` (integer): How many of Balad's top places to time (2-8).
- `lat` (number, required): Latitude in degrees, e.g. 35.7448.
- `lng` (number, required): Longitude in degrees, e.g. 51.3753.
- `open_now` (boolean): Only places Balad marks as open right now.
- `radius_km` (number): Search box half-width in km, e.g. 3 (0.5-20).
- `what` (string, required): A category slug from bl_categories (e.g. pharmacy, restaurant, gas-station, atm) or free text (e.g. پیتزا, کافه).

### `bl_along_route` (~324 tokens)

Places along a driving route

Find places of one kind (gas station, restaurant, pharmacy...) along the suggested driving route between two points.

Use it for "a gas station on my way to Shiraz" or "a cafe on the way home". Places are ordered by where they
come on the route (`km_from_start`) with how far off the road they are. Balad is searched in up to 12 boxes
spaced along the route, so on long trips (hundreds of km) places between boxes are missed; split the trip
with nearer destinations for full coverage. Details of a place: bl_place.

Input parameters:

- `from_lat` (number, required): Latitude in degrees, e.g. 35.7448.
- `from_lng` (number, required): Longitude in degrees, e.g. 51.3753.
- `limit` (integer): Max places to return (1-30).
- `max_off_route_km` (number): How far from the road a place may be, in km, e.g. 0.5 (0.2-3).
- `open_now` (boolean): Only places Balad marks as open right now.
- `to_lat` (number, required): Latitude in degrees, e.g. 35.7448.
- `to_lng` (number, required): Longitude in degrees, e.g. 51.3753.
- `what` (string, required): A category slug from bl_categories (e.g. pharmacy, restaurant, gas-station, atm) or free text (e.g. پیتزا, کافه).

### `bl_categories` (~74 tokens)

Place categories

List Balad's place categories with the slug bl_nearby takes, grouped (food, health, shopping, services...).

Call it when you need the exact slug for bl_nearby, bl_nearest_by_drive or bl_along_route (e.g. pharmacy,
hospital, gas-station, atm, parking).

## Diagnostics

Captured diagnostic sections: Provenance, Install scripts, Dependencies. The full working is on the page: https://verifymcp.io/servers/sepehr071-balad-mcp/balad-mcp#diagnostics

## Score history

- 2026-11-05: 79
- 2026-11-04: 79
- 2026-11-03: 79
- 2026-11-02: 79
- 2026-11-01: 79
- 2026-10-31: 64

## Common questions

### What is the Balad Maps MCP server?

Balad Maps is an MCP server listed in the public MCP registry as io.github.sepehr071/balad-mcp. Read-only Balad (balad.ir) Iran map: places nearby or on the way, details, reviews, driving routes. This page covers its PyPI package (balad-mcp).

### Is the Balad Maps MCP server safe to use?

Balad Maps scores 79 out of 100 on VerifyMCP. We found no known CVEs affecting it as of 5 November 2026. Its build provenance is signed and verified. That is a record of what we were able to check automatically, not an endorsement. The category breakdown on this page shows every signal behind the number, including the ones we could not confirm.

### What tools does the Balad Maps MCP server expose?

Balad Maps exposes 9 tools: bl_search, bl_nearby, bl_place, bl_reviews, bl_reverse_geocode, and 4 more. Their descriptions and schemas cost roughly 2,057 tokens of context every time the server is loaded.

### Is the Balad Maps MCP server still maintained?

Balad Maps is still listed as active in the MCP registry. We last reached this channel on 5 November 2026. Those dates come from our own scans of the registry and the channel itself, not from anything the publisher announced.

### What licence is the Balad Maps MCP server under?

Balad Maps declares the MIT licence, which is OSI-approved. That covers the source only, and says nothing about the cost of any service it calls.

## Links

- PyPI project: https://pypi.org/project/balad-mcp/
- Socket report: https://socket.dev/pypi/package/balad-mcp
- Repository: https://github.com/sepehr071/balad-mcp
- Changelog RSS feed: https://verifymcp.io/servers/sepehr071-balad-mcp/balad-mcp.xml
- Changelog JSON feed: https://verifymcp.io/servers/sepehr071-balad-mcp/balad-mcp.json
- HTML version of this page: https://verifymcp.io/servers/sepehr071-balad-mcp/balad-mcp