neshan-mcp 0.1.0__tar.gz

neshan_mcp-0.1.0/.github/ISSUE_TEMPLATE/bug_report.yml

@@ -0,0 +1,42 @@
+name: Bug report
+description: A tool failed or returned wrong data
+labels: [bug]
+body:
+  - type: input
+    id: tool
+    attributes:
+      label: Tool
+      description: Which tool, e.g. ns_search
+    validations:
+      required: true
+  - type: textarea
+    id: input
+    attributes:
+      label: Arguments and result
+      description: The arguments the agent sent and the error or wrong output. Remove anything personal.
+      render: json
+    validations:
+      required: true
+  - type: textarea
+    id: expected
+    attributes:
+      label: What you expected
+      description: e.g. what neshan.org/maps shows for the same query
+  - type: input
+    id: client
+    attributes:
+      label: MCP client and OS
+      placeholder: Claude Desktop 1.x on Windows 11
+  - type: dropdown
+    id: network
+    attributes:
+      label: Network
+      options:
+        - Direct connection
+        - VPN or proxy
+        - NESHAN_MCP_PROXY set
+  - type: input
+    id: version
+    attributes:
+      label: neshan-mcp version
+      placeholder: "0.1.0"

neshan_mcp-0.1.0/.github/ISSUE_TEMPLATE/config.yml

@@ -0,0 +1,5 @@
+blank_issues_enabled: true
+contact_links:
+  - name: Question or idea
+    url: https://github.com/sepehr071/neshan-mcp/discussions
+    about: Ask how to use it or suggest a new tool

neshan_mcp-0.1.0/.github/dependabot.yml

@@ -0,0 +1,10 @@
+version: 2
+updates:
+  - package-ecosystem: github-actions
+    directory: /
+    schedule:
+      interval: monthly
+  - package-ecosystem: uv
+    directory: /
+    schedule:
+      interval: monthly

neshan_mcp-0.1.0/.github/workflows/ci.yml

@@ -0,0 +1,22 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python: ["3.10", "3.11", "3.12", "3.13"]
+    steps:
+      - uses: actions/checkout@v7
+      - uses: astral-sh/setup-uv@v10.2.0
+        with:
+          python-version: ${{ matrix.python }}
+      - run: uv sync --locked
+      - run: uv run ruff check .
+      - run: uv run ruff format --check .
+      - run: uv run pytest -q

neshan_mcp-0.1.0/.github/workflows/publish.yml

@@ -0,0 +1,51 @@
+name: Publish
+
+# Tag a release (git tag v0.1.0 && git push --tags) after bumping the version in
+# pyproject.toml and server.json.
+on:
+  push:
+    tags: ["v*"]
+
+jobs:
+  pypi:
+    runs-on: ubuntu-latest
+    environment: pypi
+    permissions:
+      id-token: write  # PyPI trusted publishing
+      contents: write  # GitHub Release
+    steps:
+      - uses: actions/checkout@v7
+      - uses: astral-sh/setup-uv@v10.2.0
+      - name: Check versions match the tag
+        run: |
+          TAG=${GITHUB_REF_NAME#v}
+          grep -q "^version = \"$TAG\"" pyproject.toml
+          test "$(jq -r .version server.json)" = "$TAG"
+          test "$(jq -r '.packages[0].version' server.json)" = "$TAG"
+      - run: uv sync --locked && uv run pytest -q
+      - run: uv build
+      - uses: pypa/gh-action-pypi-publish@release/v1
+      - run: gh release create "$GITHUB_REF_NAME" dist/* --generate-notes --title "$GITHUB_REF_NAME"
+        env:
+          GH_TOKEN: ${{ github.token }}
+
+  mcp-registry:
+    needs: pypi
+    runs-on: ubuntu-latest
+    permissions:
+      id-token: write  # MCP Registry login via GitHub OIDC
+      contents: read
+    steps:
+      - uses: actions/checkout@v7
+      - name: Wait for PyPI to serve the new version
+        run: |
+          for i in $(seq 1 30); do
+            curl -sf "https://pypi.org/pypi/neshan-mcp/${GITHUB_REF_NAME#v}/json" >/dev/null && exit 0
+            sleep 10
+          done
+          exit 1
+      - name: Install mcp-publisher
+        run: |
+          curl -L "https://github.com/modelcontextprotocol/registry/releases/download/v1.8.1/mcp-publisher_$(uname -s | tr '[:upper:]' '[:lower:]')_$(uname -m | sed 's/x86_64/amd64/;s/aarch64/arm64/').tar.gz" | tar xz mcp-publisher
+      - run: ./mcp-publisher login github-oidc
+      - run: ./mcp-publisher publish

neshan_mcp-0.1.0/.gitignore

@@ -0,0 +1,6 @@
+.venv/
+__pycache__/
+*.pyc
+dist/
+.pytest_cache/
+.ruff_cache/

neshan_mcp-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Sepehr Radmard
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

neshan_mcp-0.1.0/PKG-INFO

@@ -0,0 +1,436 @@
+Metadata-Version: 2.5
+Name: neshan-mcp
+Version: 0.1.0
+Summary: Unofficial read-only MCP server for Neshan (نشان), the Iranian map: place search, details, reviews, photos and nearby places, reverse geocoding, air quality, car, motorcycle, bicycle, walking and transit directions, travel times and Tehran traffic-zone checks.
+Project-URL: Homepage, https://github.com/sepehr071/neshan-mcp
+Project-URL: Issues, https://github.com/sepehr071/neshan-mcp/issues
+Project-URL: Website, https://mcpfarsi.ir/
+Author-email: Sepehr Radmard <sepehrr80@gmail.com>
+License-Expression: MIT
+License-File: LICENSE
+Keywords: air-quality,directions,geocoding,iran-map,mcp,model-context-protocol,neshan,neshan-map,persian,places,public-transit,reverse-geocoding,routing,tehran,traffic
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Classifier: Topic :: Scientific/Engineering :: GIS
+Requires-Python: >=3.10
+Requires-Dist: curl-cffi>=0.16.3
+Requires-Dist: httpx-curl-cffi>=0.1.5
+Requires-Dist: httpx>=0.27
+Requires-Dist: mcp<3,>=2.2
+Description-Content-Type: text/markdown
+
+<!-- mcp-name: io.github.sepehr071/neshan-mcp -->
+
+<div align="center">
+
+<img src="https://raw.githubusercontent.com/sepehr071/neshan-mcp/main/.github/banner.png" alt="neshan-mcp: unofficial Neshan map MCP server for Claude, Cursor and Copilot, showing a live route from Azadi Tower to the Tehran Grand Bazaar" width="100%">
+
+# neshan-mcp: Neshan map of Iran MCP server for AI agents
+
+**Let your AI agent search places, get directions and check Tehran's traffic zones on Neshan (نشان).**<br>
+`neshan-mcp` is an unofficial, read-only MCP server for [Neshan](https://neshan.org/maps), the Iranian map and navigation app.<br>
+Its 11 tools cover place search, place details, reviews, photos and menus, nearby places, reverse geocoding, city air quality,
+car, motorcycle, bicycle, walking and bus/metro directions, travel times to several places and Tehran traffic-zone checks.
+No API key or account is needed.
+
+[![PyPI](https://img.shields.io/pypi/v/neshan-mcp?color=2563eb)](https://pypi.org/project/neshan-mcp/)
+[![Python](https://img.shields.io/pypi/pyversions/neshan-mcp)](https://pypi.org/project/neshan-mcp/)
+[![CI](https://github.com/sepehr071/neshan-mcp/actions/workflows/ci.yml/badge.svg)](https://github.com/sepehr071/neshan-mcp/actions/workflows/ci.yml)
+[![MCP Registry](https://img.shields.io/badge/MCP_Registry-io.github.sepehr071%2Fneshan--mcp-7c3aed)](https://registry.modelcontextprotocol.io/?q=neshan-mcp)
+[![License: MIT](https://img.shields.io/badge/license-MIT-16a34a)](https://github.com/sepehr071/neshan-mcp/blob/main/LICENSE)
+
+[![Install in VS Code](https://img.shields.io/badge/VS_Code-Install_neshan--mcp-0098FF?style=flat-square&logo=visualstudiocode&logoColor=white)](https://vscode.dev/redirect/mcp/install?name=neshan&config=%7B%22command%22%3A%22uvx%22%2C%22args%22%3A%5B%22neshan-mcp%22%5D%7D)
+
+[For AI agents](#for-ai-agents) · [Quick start](#quick-start) · [What it can do](#what-it-can-do) · [Tools](#tools) · [FAQ](#faq) · [فارسی](#فارسی)
+
+</div>
+
+---
+
+## For AI agents
+
+- **What:** unofficial MCP server (model context protocol) for neshan.org/maps, the Neshan map of Iran. Queries can be Persian or English; answers keep Neshan's Persian names, addresses and steps.
+- **Install:** `uvx neshan-mcp` or `claude mcp add neshan -- uvx neshan-mcp`. Transport: stdio. Needs [uv](https://docs.astral.sh/uv/getting-started/installation/) (Python 3.10+).
+- **Auth:** none, no API key or account. Optional `NESHAN_MCP_PROXY` (HTTP proxy URL, or a comma-separated list); system proxy settings are ignored.
+- **Access:** read-only. It cannot log in, save places or post reviews, so no confirmation is needed before calling any tool.
+- **Tools:** 11, all prefixed `ns_`. Typical sequences: `ns_search` -> `ns_place` / `ns_reviews` / `ns_photos` / `ns_nearby`;
+  `ns_search` -> `ns_travel_times` -> `ns_route`; `ns_zone_check` before driving into central Tehran.
+- **Use when:** the user asks where something is in Iran, what is near a place, whether a business is open, what people say about it or what its menu looks like, what address a coordinate is, how polluted a city's air is, whether an address is inside Tehran's traffic zone, or how to get from A to B and how long it takes, now or at a given time.
+- **Do not use when:** the user wants places outside Iran, taxi or delivery prices, or to save places in a Neshan account.
+- **Output:** compact JSON. Coordinates are `lat,lng` (latitude first). Distances in metres or km, times in minutes, fares in Toman, review dates in the Persian calendar, departure times in Tehran time.
+- **Network:** every tool works from an Iranian connection. Through a foreign connection all tools worked in testing except `ns_nearby`, which Neshan answers with HTTP 403; set `NESHAN_MCP_PROXY` to an Iranian proxy for it.
+- **Machine-readable:** [`server.json`](https://github.com/sepehr071/neshan-mcp/blob/main/server.json) and the
+  [iran-mcp catalog](https://github.com/sepehr071/iran-mcp).
+
+## Why
+
+Neshan knows Iran in detail: businesses with opening hours and reviews, live traffic, Tehran's traffic and odd-even
+plans, bus, BRT and metro lines. Its developer API needs a paid key, and its web map is built for clicking.
+`neshan-mcp` gives an agent the same public data the web map shows any visitor, in a few small calls:
+
+> **You:** How long does it take to drive from Azadi Tower to the Tehran Grand Bazaar, and will I enter the traffic zone?
+>
+> **Agent:** *calls* `ns_search("برج آزادی")`, `ns_search("بازار بزرگ تهران")`, then
+> `ns_route(origin="35.699739,51.338097", destination="35.671897,51.422428", steps=false)`
+>
+> Neshan suggests 48 minutes (13 km) via Jomhouri-e Eslami and Mostafa Khomeini streets; the route via Saeedi
+> expressway and Shoush is 16 km and takes 45 minutes. All three routes enter the traffic-plan zone (طرح ترافیک)
+> and the odd-even zone, which run from 06:30 to 18:00. The bazaar itself is inside both zones.
+
+<sub>Real answer from a live call on 2026-10-31 at 17:21 Tehran time; times change with traffic.</sub>
+
+Every reply is compact JSON with only the fields that matter, so it does not flood the agent's context.
+
+## What it can do
+
+- **Find places** by name or category near a city or a point: cafes, pharmacies, petrol stations, streets, squares. Filter by open now and rating, the way the site does
+- **Read a place**: address, coordinates, phones, website, rating and votes, open now, hours for each weekday, newest photos
+- **Read reviews**, newest first or the ones Neshan features, and **browse photos**, including the menu album
+- **See what is nearby**: restaurants, cafes, parks, toilets, banks, ATMs, parking and bus stops around a place
+- **Reverse geocode** a coordinate into a street address and province
+- **Check air quality**: today's AQI of a city, its pollutants and every monitoring station, or the index at a point
+- **Get directions** by car, motorcycle, bicycle or on foot: alternatives, live travel time, Persian turn-by-turn steps, up to 3 stops
+- **Plan by time**: leave at a given time or arrive by one (car, Tehran, Karaj and Mashhad), with Neshan's traffic forecast
+- **Rank by travel time**: one origin to up to 10 places, fastest first
+- **Check Tehran's zones**: is a point inside the traffic-plan zone or the odd-even zone, and does a route enter them; avoid them or toll roads
+- **Take public transport**: bus, BRT and metro options with lines, stops, walking and fares in Toman
+- **Read-only by design**: no login, no saving, no posting
+
+Example prompts:
+
+- "Find 24-hour pharmacies near Milad Tower that are open now and rated 4 or more."
+- "Is Lamiz Coffee in Gisha open now? What's its phone number, and what do people say about it?"
+- "Show me the menu photos of Milad Tower."
+- "Which of these three branches is closest by car from Azadi Square?"
+- "I need to be at Milad Tower at 9 tomorrow. When should I leave from Azadi Square?"
+- "Is Ferdowsi Square inside Tehran's traffic zone?"
+- "How polluted is the air in Isfahan today?"
+- <span dir="rtl">نزدیک‌ترین داروخانه شبانه‌روزی به برج میلاد کجاست؟</span>
+- <span dir="rtl">از میدان آزادی تا بازار تهران با ماشین چقدر راه است؟ وارد طرح ترافیک می‌شوم؟</span>
+- <span dir="rtl">با مترو و اتوبوس از میدان آزادی به برج میلاد چطور بروم و هزینه‌اش چقدر است؟</span>
+
+## Quick start
+
+You need [uv](https://docs.astral.sh/uv/getting-started/installation/). No API key or account.
+
+<details open>
+<summary><b>Claude Code</b></summary>
+
+```bash
+claude mcp add neshan -- uvx neshan-mcp
+```
+</details>
+
+<details>
+<summary><b>Claude Desktop</b></summary>
+
+Settings → Developer → Edit Config, then add:
+
+```json
+{
+  "mcpServers": {
+    "neshan": { "command": "uvx", "args": ["neshan-mcp"] }
+  }
+}
+```
+</details>
+
+<details>
+<summary><b>Cursor</b></summary>
+
+Add the Claude Desktop block above to `~/.cursor/mcp.json` (or `.cursor/mcp.json` in a project).
+</details>
+
+<details>
+<summary><b>VS Code (Copilot agent mode)</b></summary>
+
+Click **Install in VS Code** above, or add to `.vscode/mcp.json`:
+
+```json
+{
+  "servers": {
+    "neshan": { "type": "stdio", "command": "uvx", "args": ["neshan-mcp"] }
+  }
+}
+```
+</details>
+
+<details>
+<summary><b>Codex CLI</b></summary>
+
+```bash
+codex mcp add neshan -- uvx neshan-mcp
+```
+
+Or in `~/.codex/config.toml`:
+
+```toml
+[mcp_servers.neshan]
+command = "uvx"
+args = ["neshan-mcp"]
+```
+</details>
+
+<details>
+<summary><b>Gemini CLI</b></summary>
+
+Add to `~/.gemini/settings.json`:
+
+```json
+{
+  "mcpServers": {
+    "neshan": { "command": "uvx", "args": ["neshan-mcp"] }
+  }
+}
+```
+</details>
+
+<details>
+<summary><b>Windsurf</b></summary>
+
+Add the Claude Desktop block to `~/.codeium/windsurf/mcp_config.json`.
+</details>
+
+<details>
+<summary><b>Anything else</b></summary>
+
+It is a standard stdio MCP server: run `uvx neshan-mcp`, or `pip install neshan-mcp` and run `neshan-mcp`.
+</details>
+
+## Tools
+
+Points are `lat,lng`, e.g. `35.6997,51.3380`. Place ids come from `ns_search`.
+
+| Tool | What it does |
+|---|---|
+| `ns_search` | Find places, businesses, streets and squares on the Neshan map by name or category near a city or point |
+| `ns_place` | Get one place's details on Neshan: address, coordinates, phones, website, rating, opening hours and photos |
+| `ns_reviews` | List visitors' reviews of a place on Neshan: star rating, Persian date, comment, likes and owner reply |
+| `ns_photos` | List a place's photos on Neshan as image URLs, 10 per page, with date and uploader, including menu photos |
+| `ns_nearby` | List what is around a place on Neshan by category: restaurants, cafes, parks, toilets, banks, ATMs, parking |
+| `ns_reverse_geocode` | Turn a latitude/longitude into Neshan's street address and province (reverse geocoding) |
+| `ns_air_quality` | Get today's air quality index (AQI) of an Iranian city from Neshan, with pollutants and the readings of each station |
+| `ns_route` | Get car, motorcycle, bicycle or walking directions on Neshan: distance, travel time and turn-by-turn steps |
+| `ns_travel_times` | Get the travel time from one point to several places on Neshan, fastest first |
+| `ns_zone_check` | Check whether a point is inside Tehran's traffic-plan zone or odd-even (air-pollution) zone, with plan hours |
+| `ns_transit_route` | Get bus, BRT and metro options between two points on Neshan, with lines, stops, walking and fares |
+
+All 11 tools are annotated `readOnlyHint: true`.
+
+## How it works
+
+```text
+  AI agent  (Claude, Cursor, Copilot, ...)
+      │
+      │  MCP over stdio
+      ▼
+  neshan-mcp  (runs on your machine)
+      │
+      │  HTTPS
+      └──────▶  neshan.org/maps/pwa-api   search, places, reviews, photos, routes, transit, air quality
+```
+
+`neshan-mcp` runs locally and calls the same endpoints the neshan.org/maps web app uses, with no hosted server in
+between and no API key. Requests go out through a Chrome-impersonating client and look like the web app's own.
+It sends at most 3 requests at a time with a little jitter, caches answers (places and addresses for 5 minutes,
+live routes for 1 minute, transit, zones and air quality for 10 minutes), retries a failed call up to twice, and
+only talks to `neshan.org`.
+
+Neshan's web app encodes most of its answers: they arrive as shuffled base64 text, and transit answers are also
+XOR-encoded. The server decodes them the same way the web app's own script does. If Neshan changes the scheme, the
+server reads the new values from the site's current JavaScript once, the way a browser loads it, and retries. An
+answer it still cannot read is reported as an error, never as made-up data.
+
+## Good to know
+
+- **Coordinates are `lat,lng`.** Latitude first. A swapped pair is rejected with a hint.
+- **`near` takes a city or a point.** 23 big cities by name in English or Persian (Tehran, Mashhad, Isfahan, Shiraz,
+  Tabriz, Karaj, Qom, Ahvaz, ...). For a smaller town, put its name in the query.
+- **Search returns at most 30 places**, with no paging. Sponsored results (marked آگهی on the site) are left out.
+  `open_now` and `min_rating` use Neshan's own filters (open now; 3.5+, 4+, 4.5+).
+- **Travel times are Neshan's estimates** for leaving now, or for `depart_at`. Departure and arrival times are
+  Tehran time (`YYYY-MM-DD HH:MM`, Gregorian); Neshan offers them for cars in Tehran, Karaj and Mashhad.
+- **Toll roads are flagged** (`toll_road`), but not priced: Neshan's web app never shows a toll amount.
+- **Transit has no travel time.** Neshan's web map gives fares, lines and stops, but no duration, for bus and metro.
+- **`ns_nearby` needs an Iranian connection.** Neshan answers it with HTTP 403 from abroad; set `NESHAN_MCP_PROXY`
+  to an Iranian proxy, or use `ns_search` with the place's `lat,lng` as `near`.
+- **Air-quality cities** use their English name (`Tehran`, `bandar abbas`) or the Persian name for the 23 cities above.
+  A city without monitoring stations returns "no data".
+- **Persian output.** Names, addresses, hours (Persian digits), steps and review dates are as Neshan shows them.
+- **What it does not do:** no login, saving or reviewing; no places outside Iran; no live traffic incidents; no
+  temperature or AI review summaries (Neshan serves those only to signed-in users).
+
+## FAQ
+
+<details>
+<summary><b>Is there a Neshan MCP server or a free Neshan API?</b></summary>
+
+Neshan sells a developer API that needs an API key. `neshan-mcp` is an unofficial MCP server with 11 read-only
+tools that calls the public endpoints of the neshan.org web map instead, so it needs no key, account or payment.
+</details>
+
+<details>
+<summary><b>Does it need a Neshan API key?</b></summary>
+
+No. It uses no API key, token or login. Install it with `uvx neshan-mcp` and ask in plain language.
+</details>
+
+<details>
+<summary><b>Is my car allowed in Tehran's traffic zone right now?</b></summary>
+
+`ns_zone_check` tells you whether a point is inside the traffic-plan zone (طرح ترافیک) or the odd-even zone (طرح
+آلودگی هوا) and the hours Neshan shows for each plan, e.g. 06:30 to 18:00. Whether your own car may enter depends on
+your permit and plate, which the server does not know. `ns_route` can route around both zones with
+`avoid_traffic_zone` and `avoid_odd_even`.
+</details>
+
+<details>
+<summary><b>What is Tehran's air quality today?</b></summary>
+
+Ask the agent; `ns_air_quality("Tehran")` returns today's AQI on the 0-500 scale with Neshan's label (e.g. قابل قبول,
+acceptable), the pollutant readings and every monitoring station, most polluted first.
+</details>
+
+<details>
+<summary><b>How do I use it with Claude, Cursor or Copilot?</b></summary>
+
+Add the server with `claude mcp add neshan -- uvx neshan-mcp`, or use the matching config in
+[Quick start](#quick-start), then ask in Persian or English.
+</details>
+
+<details>
+<summary><b>Does it work outside Iran?</b></summary>
+
+Yes, except for `ns_nearby`. Everything else worked through a foreign connection in testing. If your network is
+blocked, set `NESHAN_MCP_PROXY` to an HTTP proxy. System proxy variables are ignored on purpose.
+</details>
+
+<details>
+<summary><b>How is it different from balad-mcp?</b></summary>
+
+[balad-mcp](https://github.com/sepehr071/balad-mcp) reads Balad, another Iranian map. Both search places and give
+directions; `neshan-mcp` adds bicycle, walking and public-transit routes, departure-time routing, a zone check for any
+point in Tehran and air quality. You can install both and compare.
+</details>
+
+<details>
+<summary><b>Can it save places or write reviews?</b></summary>
+
+No. It has no login and only reads public data.
+</details>
+
+<details>
+<summary><b>How do I debug what the agent sees?</b></summary>
+
+```bash
+npx @modelcontextprotocol/inspector uvx neshan-mcp
+```
+</details>
+
+## Configuration
+
+| Variable | Default | Meaning |
+|---|---|---|
+| `NESHAN_MCP_PROXY` | unset | Optional HTTP proxy URL for the neshan.org requests; system proxy settings are ignored. A comma-separated list is used one at a time: the next proxy takes over when one is blocked or cannot connect |
+
+<a id="فارسی"></a>
+
+## فارسی: سرور MCP نقشه نشان
+
+<div dir="rtl">
+
+**neshan-mcp** یک سرور MCP غیررسمی و فقط‌خواندنی برای [نقشه نشان](https://neshan.org/maps) است. با آن دستیار هوش مصنوعی شما (Claude، Cursor، Copilot و برنامه‌های دیگر) می‌تواند مکان‌ها را پیدا کند، مسیر بدهد و محدوده طرح ترافیک تهران را بررسی کند. کلید API و حساب کاربری لازم نیست.
+
+**چه کارهایی می‌کند**
+
+- **جستجوی مکان** با نام یا دسته (کافه، داروخانه، پمپ بنزین، خیابان، میدان) در یک شهر یا نزدیک یک نقطه، با فیلتر «باز باشد» و امتیاز، همان‌طور که در سایت نشان است.
+- **جزئیات مکان**: آدرس، مختصات، تلفن، وب‌سایت، امتیاز، ساعت کاری هر روز هفته و تازه‌ترین عکس‌ها.
+- **نظرات کاربران** (تازه‌ترین یا برگزیده) و **عکس‌ها**، از جمله عکس منو.
+- **امکانات نزدیک** هر مکان: رستوران، کافه، پارک، سرویس بهداشتی، بانک، خودپرداز، پارکینگ و ایستگاه اتوبوس.
+- **تبدیل مختصات به آدرس**.
+- **کیفیت هوا**: شاخص امروز هر شهر، آلاینده‌ها و همه ایستگاه‌های سنجش.
+- **مسیریابی** با خودرو، موتور، دوچرخه و پیاده، با زمان سفر زنده، گام‌های مسیر به فارسی و تا ۳ توقف بین راه.
+- **مسیریابی با زمان حرکت یا رسیدن** برای خودرو در تهران، کرج و مشهد، با پیش‌بینی ترافیک نشان.
+- **مقایسه زمان سفر** از یک مبدا تا حداکثر ۱۰ مقصد، از سریع‌ترین به کندترین.
+- **طرح ترافیک و زوج و فرد**: آیا یک نقطه داخل محدوده است و آیا مسیر وارد آن می‌شود، با امکان دور زدن محدوده‌ها و عوارضی.
+- **حمل‌ونقل عمومی**: گزینه‌های اتوبوس، بی‌آرتی و مترو با خط‌ها، ایستگاه‌ها و هزینه سفر به تومان.
+
+**نکته‌ها**
+
+- فقط‌خواندنی است: وارد حساب نمی‌شود، مکانی ذخیره نمی‌کند و نظر ثبت نمی‌کند.
+- مختصات را به شکل `lat,lng` بدهید، یعنی اول عرض جغرافیایی (مثل `35.6997,51.3380`).
+- ابزار امکانات نزدیک (`ns_nearby`) فقط با اینترنت ایران کار می‌کند. بیرون از ایران متغیر `NESHAN_MCP_PROXY` را روی یک پراکسی با خروجی ایران بگذارید.
+- زمان حرکت و رسیدن به وقت تهران و تاریخ میلادی است (مثل `2026-11-01 08:00`).
+- برای مسیرهای عوارضی فقط نشانه عوارضی بودن برمی‌گردد، چون خود سایت نشان مبلغ عوارض را نمایش نمی‌دهد.
+- پاسخ‌های سایت نشان رمزگذاری‌شده است و این سرور آن‌ها را به همان روشی باز می‌کند که خود سایت باز می‌کند.
+
+**نصب** (اول [uv](https://docs.astral.sh/uv/getting-started/installation/) را نصب کنید). در Claude Code:
+
+</div>
+
+```bash
+claude mcp add neshan -- uvx neshan-mcp
+```
+
+<div dir="rtl">
+
+در Claude Desktop، Cursor و برنامه‌های دیگر همان تنظیم بخش [Quick start](#quick-start) را بگذارید.
+
+**نمونه پرسش‌ها**
+
+- «نزدیک‌ترین داروخانه شبانه‌روزی به برج میلاد کجاست و الان باز است؟»
+- «از میدان آزادی تا بازار تهران با ماشین چقدر طول می‌کشد؟ وارد طرح ترافیک می‌شوم؟»
+- «فردا ساعت ۹ باید برج میلاد باشم؛ کی از میدان آزادی راه بیفتم؟»
+- «با مترو و اتوبوس از میدان آزادی به برج میلاد چطور بروم و چقدر خرج دارد؟»
+- «هوای اصفهان امروز آلوده است؟»
+- «کافه لمیز گیشا الان باز است؟ مردم درباره‌اش چه گفته‌اند؟»
+
+</div>
+
+## Development
+
+```bash
+git clone https://github.com/sepehr071/neshan-mcp && cd neshan-mcp
+uv sync
+uv run ruff check . && uv run ruff format --check .
+uv run python -m pytest -q          # offline unit tests
+uv run python -m pytest -m live -q  # calls neshan.org
+uv build
+```
+
+Place tools live in `src/neshan_mcp/maps.py`, routing tools in `src/neshan_mcp/routes.py` and the decoding of
+Neshan's answers in `src/neshan_mcp/codec.py`. Each tool is a typed async function with a docstring that tells the
+agent when to use it. Issues and PRs are welcome.
+
+Releases: bump the version in `pyproject.toml` and `server.json`, then push a `v*` tag. GitHub Actions publishes to PyPI.
+
+## Related servers
+
+- [balad-mcp](https://github.com/sepehr071/balad-mcp) for Balad, another Iranian map: places, reviews and driving routes
+- [iran-mcp](https://github.com/sepehr071/iran-mcp): catalog of all Iranian-service MCP servers
+- [mrbilit-mcp](https://github.com/sepehr071/mrbilit-mcp) for Iranian flights, trains, buses and hotels
+- [jabama-mcp](https://github.com/sepehr071/jabama-mcp) for villas and stays across Iran
+- [snapp-mcp](https://github.com/sepehr071/snapp-mcp) for Snappfood and SnappMarket
+
+## Disclaimer
+
+Unofficial and not affiliated with or endorsed by Neshan. It is read-only and uses the endpoints of the neshan.org
+web app, which can change without notice. Travel times, zone hours and air quality are informational; check
+official sources before relying on them.
+
+## Author
+
+<a href="https://www.linkedin.com/in/sepehr-radmard"><img src="https://raw.githubusercontent.com/sepehr071/iran-mcp/main/assets/author-banner.png" alt="Sepehr Radmard: open-source MCP servers for the Iranian web. LinkedIn: linkedin.com/in/sepehr-radmard" width="100%"></a>
+
+Built and maintained by **Sepehr Radmard** (سپهر رادمرد). Connect on [LinkedIn](https://www.linkedin.com/in/sepehr-radmard) or follow [@sepehr071 on GitHub](https://github.com/sepehr071) for more MCP servers for Iranian websites, all listed in [iran-mcp](https://github.com/sepehr071/iran-mcp). If this saves you time, a star on the repo helps other people find it.
+
+## License
+
+[MIT](https://github.com/sepehr071/neshan-mcp/blob/main/LICENSE)