mrbilit-mcp 0.1.0__tar.gz
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- mrbilit_mcp-0.1.0/.github/ISSUE_TEMPLATE/bug_report.yml +42 -0
- mrbilit_mcp-0.1.0/.github/ISSUE_TEMPLATE/config.yml +5 -0
- mrbilit_mcp-0.1.0/.github/banner.png +0 -0
- mrbilit_mcp-0.1.0/.github/dependabot.yml +10 -0
- mrbilit_mcp-0.1.0/.github/workflows/ci.yml +22 -0
- mrbilit_mcp-0.1.0/.github/workflows/publish.yml +51 -0
- mrbilit_mcp-0.1.0/.gitignore +6 -0
- mrbilit_mcp-0.1.0/LICENSE +21 -0
- mrbilit_mcp-0.1.0/PKG-INFO +365 -0
- mrbilit_mcp-0.1.0/README.md +339 -0
- mrbilit_mcp-0.1.0/pyproject.toml +54 -0
- mrbilit_mcp-0.1.0/server.json +32 -0
- mrbilit_mcp-0.1.0/src/mrbilit_mcp/__init__.py +5 -0
- mrbilit_mcp-0.1.0/src/mrbilit_mcp/buses.py +293 -0
- mrbilit_mcp-0.1.0/src/mrbilit_mcp/content.py +230 -0
- mrbilit_mcp-0.1.0/src/mrbilit_mcp/flights.py +381 -0
- mrbilit_mcp-0.1.0/src/mrbilit_mcp/hotels.py +364 -0
- mrbilit_mcp-0.1.0/src/mrbilit_mcp/http.py +199 -0
- mrbilit_mcp-0.1.0/src/mrbilit_mcp/places.py +231 -0
- mrbilit_mcp-0.1.0/src/mrbilit_mcp/registry.py +16 -0
- mrbilit_mcp-0.1.0/src/mrbilit_mcp/server.py +64 -0
- mrbilit_mcp-0.1.0/src/mrbilit_mcp/snapshot.json +1 -0
- mrbilit_mcp-0.1.0/src/mrbilit_mcp/trains.py +391 -0
- mrbilit_mcp-0.1.0/tests/conftest.py +98 -0
- mrbilit_mcp-0.1.0/tests/fixtures/airlines.json +51 -0
- mrbilit_mcp-0.1.0/tests/fixtures/airport_search.json +28 -0
- mrbilit_mcp-0.1.0/tests/fixtures/bus_cities.json +354 -0
- mrbilit_mcp-0.1.0/tests/fixtures/bus_companies.json +68 -0
- mrbilit_mcp-0.1.0/tests/fixtures/bus_min_prices.json +33 -0
- mrbilit_mcp-0.1.0/tests/fixtures/bus_nearby.json +43 -0
- mrbilit_mcp-0.1.0/tests/fixtures/bus_search.json +432 -0
- mrbilit_mcp-0.1.0/tests/fixtures/bus_seats.json +224 -0
- mrbilit_mcp-0.1.0/tests/fixtures/chunk_airports.js +2 -0
- mrbilit_mcp-0.1.0/tests/fixtures/chunk_stations.js +2 -0
- mrbilit_mcp-0.1.0/tests/fixtures/faqs.json +49 -0
- mrbilit_mcp-0.1.0/tests/fixtures/flight_baggage.json +6 -0
- mrbilit_mcp-0.1.0/tests/fixtures/flight_fare_rules.txt +1 -0
- mrbilit_mcp-0.1.0/tests/fixtures/flight_min_prices.json +72 -0
- mrbilit_mcp-0.1.0/tests/fixtures/flight_search.json +696 -0
- mrbilit_mcp-0.1.0/tests/fixtures/flight_search_back.json +506 -0
- mrbilit_mcp-0.1.0/tests/fixtures/flight_search_intl_rt.json +608 -0
- mrbilit_mcp-0.1.0/tests/fixtures/hotel_autocomplete.json +63 -0
- mrbilit_mcp-0.1.0/tests/fixtures/hotel_calendar.json +42 -0
- mrbilit_mcp-0.1.0/tests/fixtures/hotel_detail.json +300 -0
- mrbilit_mcp-0.1.0/tests/fixtures/hotel_rooms.json +235 -0
- mrbilit_mcp-0.1.0/tests/fixtures/hotel_search.json +464 -0
- mrbilit_mcp-0.1.0/tests/fixtures/hotel_static.json +270 -0
- mrbilit_mcp-0.1.0/tests/fixtures/mag_posts.json +26 -0
- mrbilit_mcp-0.1.0/tests/fixtures/masir.json +282 -0
- mrbilit_mcp-0.1.0/tests/fixtures/messages.json +30 -0
- mrbilit_mcp-0.1.0/tests/fixtures/nearby_airports.json +23 -0
- mrbilit_mcp-0.1.0/tests/fixtures/route_content.json +50 -0
- mrbilit_mcp-0.1.0/tests/fixtures/site_entry.js +2 -0
- mrbilit_mcp-0.1.0/tests/fixtures/site_home.html +1 -0
- mrbilit_mcp-0.1.0/tests/fixtures/support_help.json +44 -0
- mrbilit_mcp-0.1.0/tests/fixtures/taxi_cities.json +104 -0
- mrbilit_mcp-0.1.0/tests/fixtures/taxi_search.json +378 -0
- mrbilit_mcp-0.1.0/tests/fixtures/terms.json +21 -0
- mrbilit_mcp-0.1.0/tests/fixtures/train_companies.json +78 -0
- mrbilit_mcp-0.1.0/tests/fixtures/train_min_prices.json +20 -0
- mrbilit_mcp-0.1.0/tests/fixtures/train_nearby.json +36 -0
- mrbilit_mcp-0.1.0/tests/fixtures/train_pricing.json +31 -0
- mrbilit_mcp-0.1.0/tests/fixtures/train_search.json +615 -0
- mrbilit_mcp-0.1.0/tests/fixtures/train_stops.json +26 -0
- mrbilit_mcp-0.1.0/tests/test_buses.py +156 -0
- mrbilit_mcp-0.1.0/tests/test_content.py +99 -0
- mrbilit_mcp-0.1.0/tests/test_flights.py +235 -0
- mrbilit_mcp-0.1.0/tests/test_hotels.py +179 -0
- mrbilit_mcp-0.1.0/tests/test_http.py +63 -0
- mrbilit_mcp-0.1.0/tests/test_live_buses.py +33 -0
- mrbilit_mcp-0.1.0/tests/test_live_content.py +26 -0
- mrbilit_mcp-0.1.0/tests/test_live_flights.py +29 -0
- mrbilit_mcp-0.1.0/tests/test_live_hotels.py +35 -0
- mrbilit_mcp-0.1.0/tests/test_live_places.py +18 -0
- mrbilit_mcp-0.1.0/tests/test_live_trains.py +41 -0
- mrbilit_mcp-0.1.0/tests/test_places.py +121 -0
- mrbilit_mcp-0.1.0/tests/test_trains.py +187 -0
- mrbilit_mcp-0.1.0/uv.lock +1112 -0
|
@@ -0,0 +1,42 @@
|
|
|
1
|
+
name: Bug report
|
|
2
|
+
description: A tool failed or returned wrong data
|
|
3
|
+
labels: [bug]
|
|
4
|
+
body:
|
|
5
|
+
- type: input
|
|
6
|
+
id: tool
|
|
7
|
+
attributes:
|
|
8
|
+
label: Tool
|
|
9
|
+
description: Which tool, e.g. mb_search_flights
|
|
10
|
+
validations:
|
|
11
|
+
required: true
|
|
12
|
+
- type: textarea
|
|
13
|
+
id: input
|
|
14
|
+
attributes:
|
|
15
|
+
label: Arguments and result
|
|
16
|
+
description: The arguments the agent sent and the error or wrong output. Remove anything personal.
|
|
17
|
+
render: json
|
|
18
|
+
validations:
|
|
19
|
+
required: true
|
|
20
|
+
- type: textarea
|
|
21
|
+
id: expected
|
|
22
|
+
attributes:
|
|
23
|
+
label: What you expected
|
|
24
|
+
description: e.g. the price shown on mrbilit.com for the same route, date and passengers
|
|
25
|
+
- type: input
|
|
26
|
+
id: client
|
|
27
|
+
attributes:
|
|
28
|
+
label: MCP client and OS
|
|
29
|
+
placeholder: Claude Desktop 1.x on Windows 11
|
|
30
|
+
- type: dropdown
|
|
31
|
+
id: network
|
|
32
|
+
attributes:
|
|
33
|
+
label: Network
|
|
34
|
+
options:
|
|
35
|
+
- Iranian IP, no VPN
|
|
36
|
+
- VPN or proxy
|
|
37
|
+
- MRBILIT_MCP_PROXY set
|
|
38
|
+
- type: input
|
|
39
|
+
id: version
|
|
40
|
+
attributes:
|
|
41
|
+
label: mrbilit-mcp version
|
|
42
|
+
placeholder: "0.1.0"
|
|
Binary file
|
|
@@ -0,0 +1,22 @@
|
|
|
1
|
+
name: CI
|
|
2
|
+
|
|
3
|
+
on:
|
|
4
|
+
push:
|
|
5
|
+
branches: [main]
|
|
6
|
+
pull_request:
|
|
7
|
+
|
|
8
|
+
jobs:
|
|
9
|
+
test:
|
|
10
|
+
runs-on: ubuntu-latest
|
|
11
|
+
strategy:
|
|
12
|
+
matrix:
|
|
13
|
+
python: ["3.10", "3.11", "3.12", "3.13"]
|
|
14
|
+
steps:
|
|
15
|
+
- uses: actions/checkout@v7
|
|
16
|
+
- uses: astral-sh/setup-uv@v10.2.0
|
|
17
|
+
with:
|
|
18
|
+
python-version: ${{ matrix.python }}
|
|
19
|
+
- run: uv sync --locked
|
|
20
|
+
- run: uv run ruff check .
|
|
21
|
+
- run: uv run ruff format --check .
|
|
22
|
+
- run: uv run pytest -q
|
|
@@ -0,0 +1,51 @@
|
|
|
1
|
+
name: Publish
|
|
2
|
+
|
|
3
|
+
# Tag a release (git tag v0.1.0 && git push --tags) after bumping the version in
|
|
4
|
+
# pyproject.toml and server.json.
|
|
5
|
+
on:
|
|
6
|
+
push:
|
|
7
|
+
tags: ["v*"]
|
|
8
|
+
|
|
9
|
+
jobs:
|
|
10
|
+
pypi:
|
|
11
|
+
runs-on: ubuntu-latest
|
|
12
|
+
environment: pypi
|
|
13
|
+
permissions:
|
|
14
|
+
id-token: write # PyPI trusted publishing
|
|
15
|
+
contents: write # GitHub Release
|
|
16
|
+
steps:
|
|
17
|
+
- uses: actions/checkout@v7
|
|
18
|
+
- uses: astral-sh/setup-uv@v10.2.0
|
|
19
|
+
- name: Check versions match the tag
|
|
20
|
+
run: |
|
|
21
|
+
TAG=${GITHUB_REF_NAME#v}
|
|
22
|
+
grep -q "^version = \"$TAG\"" pyproject.toml
|
|
23
|
+
test "$(jq -r .version server.json)" = "$TAG"
|
|
24
|
+
test "$(jq -r '.packages[0].version' server.json)" = "$TAG"
|
|
25
|
+
- run: uv sync --locked && uv run pytest -q
|
|
26
|
+
- run: uv build
|
|
27
|
+
- uses: pypa/gh-action-pypi-publish@release/v1
|
|
28
|
+
- run: gh release create "$GITHUB_REF_NAME" dist/* --generate-notes --title "$GITHUB_REF_NAME"
|
|
29
|
+
env:
|
|
30
|
+
GH_TOKEN: ${{ github.token }}
|
|
31
|
+
|
|
32
|
+
mcp-registry:
|
|
33
|
+
needs: pypi
|
|
34
|
+
runs-on: ubuntu-latest
|
|
35
|
+
permissions:
|
|
36
|
+
id-token: write # MCP Registry login via GitHub OIDC
|
|
37
|
+
contents: read
|
|
38
|
+
steps:
|
|
39
|
+
- uses: actions/checkout@v7
|
|
40
|
+
- name: Wait for PyPI to serve the new version
|
|
41
|
+
run: |
|
|
42
|
+
for i in $(seq 1 30); do
|
|
43
|
+
curl -sf "https://pypi.org/pypi/mrbilit-mcp/${GITHUB_REF_NAME#v}/json" >/dev/null && exit 0
|
|
44
|
+
sleep 10
|
|
45
|
+
done
|
|
46
|
+
exit 1
|
|
47
|
+
- name: Install mcp-publisher
|
|
48
|
+
run: |
|
|
49
|
+
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
|
|
50
|
+
- run: ./mcp-publisher login github-oidc
|
|
51
|
+
- run: ./mcp-publisher publish
|
|
@@ -0,0 +1,21 @@
|
|
|
1
|
+
MIT License
|
|
2
|
+
|
|
3
|
+
Copyright (c) 2026 Sepehr
|
|
4
|
+
|
|
5
|
+
Permission is hereby granted, free of charge, to any person obtaining a copy
|
|
6
|
+
of this software and associated documentation files (the "Software"), to deal
|
|
7
|
+
in the Software without restriction, including without limitation the rights
|
|
8
|
+
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
|
|
9
|
+
copies of the Software, and to permit persons to whom the Software is
|
|
10
|
+
furnished to do so, subject to the following conditions:
|
|
11
|
+
|
|
12
|
+
The above copyright notice and this permission notice shall be included in all
|
|
13
|
+
copies or substantial portions of the Software.
|
|
14
|
+
|
|
15
|
+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
|
|
16
|
+
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
|
|
17
|
+
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
|
|
18
|
+
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
|
|
19
|
+
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
|
|
20
|
+
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
|
|
21
|
+
SOFTWARE.
|
|
@@ -0,0 +1,365 @@
|
|
|
1
|
+
Metadata-Version: 2.5
|
|
2
|
+
Name: mrbilit-mcp
|
|
3
|
+
Version: 0.1.0
|
|
4
|
+
Summary: Unofficial read-only MCP server for MrBilit: cheapest flights, trains, buses, taxis and hotels in Iran, with seats, refund rules and exact prices.
|
|
5
|
+
Project-URL: Homepage, https://github.com/sepehr071/mrbilit-mcp
|
|
6
|
+
Project-URL: Source, https://github.com/sepehr071/mrbilit-mcp
|
|
7
|
+
Project-URL: Changelog, https://github.com/sepehr071/mrbilit-mcp/releases
|
|
8
|
+
Project-URL: Issues, https://github.com/sepehr071/mrbilit-mcp/issues
|
|
9
|
+
Author-email: Sepehr <sepehr@nextofx.com>
|
|
10
|
+
License-Expression: MIT
|
|
11
|
+
License-File: LICENSE
|
|
12
|
+
Keywords: bus,flights,hotel,iran,mcp,model-context-protocol,mrbilit,train,travel
|
|
13
|
+
Classifier: Development Status :: 4 - Beta
|
|
14
|
+
Classifier: Intended Audience :: Developers
|
|
15
|
+
Classifier: Operating System :: OS Independent
|
|
16
|
+
Classifier: Programming Language :: Python :: 3
|
|
17
|
+
Classifier: Programming Language :: Python :: 3.10
|
|
18
|
+
Classifier: Programming Language :: Python :: 3.11
|
|
19
|
+
Classifier: Programming Language :: Python :: 3.12
|
|
20
|
+
Classifier: Programming Language :: Python :: 3.13
|
|
21
|
+
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
|
|
22
|
+
Requires-Python: >=3.10
|
|
23
|
+
Requires-Dist: httpx>=0.27
|
|
24
|
+
Requires-Dist: mcp<3,>=2.2
|
|
25
|
+
Description-Content-Type: text/markdown
|
|
26
|
+
|
|
27
|
+
<!-- mcp-name: io.github.sepehr071/mrbilit-mcp -->
|
|
28
|
+
|
|
29
|
+
<div align="center">
|
|
30
|
+
|
|
31
|
+
<img src="https://raw.githubusercontent.com/sepehr071/mrbilit-mcp/main/.github/banner.png" alt="mrbilit-mcp: let your AI agent find the cheapest way to travel in Iran" width="100%">
|
|
32
|
+
|
|
33
|
+
# ✈️ mrbilit-mcp
|
|
34
|
+
|
|
35
|
+
**Let your AI agent plan trips in Iran with MrBilit.**<br>
|
|
36
|
+
Find the cheapest flight, train, bus or private taxi on a date or over a month, see seats, baggage and refund rules,<br>
|
|
37
|
+
and compare hotels with exact room prices, all from Claude, Cursor or Copilot.
|
|
38
|
+
|
|
39
|
+
[](https://pypi.org/project/mrbilit-mcp/)
|
|
40
|
+
[](https://pypi.org/project/mrbilit-mcp/)
|
|
41
|
+
[](https://github.com/sepehr071/mrbilit-mcp/actions/workflows/ci.yml)
|
|
42
|
+
[](https://registry.modelcontextprotocol.io/?q=mrbilit-mcp)
|
|
43
|
+
[](https://github.com/sepehr071/mrbilit-mcp/blob/main/LICENSE)
|
|
44
|
+
|
|
45
|
+
[](https://cursor.com/en/install-mcp?name=mrbilit&config=eyJjb21tYW5kIjoidXZ4IiwiYXJncyI6WyJtcmJpbGl0LW1jcCJdfQ==)
|
|
46
|
+
[](https://vscode.dev/redirect/mcp/install?name=mrbilit&config=%7B%22command%22%3A%22uvx%22%2C%22args%22%3A%5B%22mrbilit-mcp%22%5D%7D)
|
|
47
|
+
|
|
48
|
+
[Quick start](#quick-start) · [What it can do](#what-it-can-do) · [Tools](#tools) · [FAQ](#faq) · [فارسی](#فارسی)
|
|
49
|
+
|
|
50
|
+
</div>
|
|
51
|
+
|
|
52
|
+
---
|
|
53
|
+
|
|
54
|
+
## Why
|
|
55
|
+
|
|
56
|
+
MrBilit (mrbilit.com, مستربلیط) sells flights, trains, intercity buses, private taxis and hotels in one place, but
|
|
57
|
+
each one has its own search, calendar and rules. Comparing "plane or train or bus, which day, which seat" means
|
|
58
|
+
a dozen page loads. An agent with `mrbilit-mcp` does it in one go:
|
|
59
|
+
|
|
60
|
+
> **You:** Cheapest way to get from Tehran to Mashhad on 20 October?
|
|
61
|
+
>
|
|
62
|
+
> **Agent:** *calls* `mb_search_flights(origin="THR", destination="MHD", date="2026-10-20")`,
|
|
63
|
+
> `mb_train_price_calendar(origin=1, destination=191)`, `mb_search_buses(origin=11320000, destination=31310000, date="2026-10-20", sort="cheapest")`
|
|
64
|
+
>
|
|
65
|
+
> | Mode | Cheapest option | Departs | Price (Toman) |
|
|
66
|
+
> |---|---|---|---|
|
|
67
|
+
> | Bus | Peyk Saba VIP, Tehran South terminal, 17 seats left | 21:00, arrives 09:00 | **1,313,000** |
|
|
68
|
+
> | Train | cheapest seat that day | | 760,000 |
|
|
69
|
+
> | Flight | Mehr Air MEH 4200, Mehrabad, 2 seats left | 08:30, arrives 09:30 | 11,856,000 |
|
|
70
|
+
>
|
|
71
|
+
> The train is cheapest; want me to list that day's trains and free seats with `mb_search_trains`?
|
|
72
|
+
|
|
73
|
+
<sub>Real tool output from 2026-10-04; prices and seats change all the time. Prices are in Toman.</sub>
|
|
74
|
+
|
|
75
|
+
## What it can do
|
|
76
|
+
|
|
77
|
+
- ✈️ **Flights**: domestic and international, one-way or round trip, party prices, cabin/airline/direct/time filters
|
|
78
|
+
- 📅 **Cheapest day** for flights, trains and buses over weeks, and the cheapest nights of a hotel
|
|
79
|
+
- 🚆 **Trains**: every class with free seats, exact price for children, infants or a whole compartment, every stop
|
|
80
|
+
- 🚌 **Buses and taxis**: terminals, companies, VIP, seat maps with women/men seats, private door-to-door cars
|
|
81
|
+
- 🔀 **Alternatives** when trains are full: one-change trips, nearby stations, bus routes and airports
|
|
82
|
+
- 🏨 **Hotels**: available stays with prices, every hotel of a city, guest ratings and reviews, rooms and exact prices
|
|
83
|
+
- 📢 **Context**: current site notices, official refund and baggage rules, help-center guides, route guides
|
|
84
|
+
- 🔒 **Read-only by design**: no login, no seat hold, no booking, no payment
|
|
85
|
+
|
|
86
|
+
## Quick start
|
|
87
|
+
|
|
88
|
+
You need [uv](https://docs.astral.sh/uv/getting-started/installation/).
|
|
89
|
+
|
|
90
|
+
<details open>
|
|
91
|
+
<summary><b>Claude Code</b></summary>
|
|
92
|
+
|
|
93
|
+
```bash
|
|
94
|
+
claude mcp add mrbilit -- uvx mrbilit-mcp
|
|
95
|
+
```
|
|
96
|
+
|
|
97
|
+
Outside Iran, if MrBilit's API does not answer, add a proxy:
|
|
98
|
+
|
|
99
|
+
```bash
|
|
100
|
+
claude mcp add mrbilit -e MRBILIT_MCP_PROXY=http://127.0.0.1:8080 -- uvx mrbilit-mcp
|
|
101
|
+
```
|
|
102
|
+
</details>
|
|
103
|
+
|
|
104
|
+
<details>
|
|
105
|
+
<summary><b>Claude Desktop</b></summary>
|
|
106
|
+
|
|
107
|
+
Settings → Developer → Edit Config, then add:
|
|
108
|
+
|
|
109
|
+
```json
|
|
110
|
+
{
|
|
111
|
+
"mcpServers": {
|
|
112
|
+
"mrbilit": { "command": "uvx", "args": ["mrbilit-mcp"] }
|
|
113
|
+
}
|
|
114
|
+
}
|
|
115
|
+
```
|
|
116
|
+
|
|
117
|
+
Need a proxy? Add `"env": { "MRBILIT_MCP_PROXY": "http://127.0.0.1:8080" }` next to `args`.
|
|
118
|
+
</details>
|
|
119
|
+
|
|
120
|
+
<details>
|
|
121
|
+
<summary><b>Cursor</b></summary>
|
|
122
|
+
|
|
123
|
+
Click **Install in Cursor** above, or add the Claude Desktop block to `~/.cursor/mcp.json`.
|
|
124
|
+
</details>
|
|
125
|
+
|
|
126
|
+
<details>
|
|
127
|
+
<summary><b>VS Code (Copilot agent mode)</b></summary>
|
|
128
|
+
|
|
129
|
+
Click **Install in VS Code** above, or add to `.vscode/mcp.json`:
|
|
130
|
+
|
|
131
|
+
```json
|
|
132
|
+
{
|
|
133
|
+
"servers": {
|
|
134
|
+
"mrbilit": { "type": "stdio", "command": "uvx", "args": ["mrbilit-mcp"] }
|
|
135
|
+
}
|
|
136
|
+
}
|
|
137
|
+
```
|
|
138
|
+
</details>
|
|
139
|
+
|
|
140
|
+
<details>
|
|
141
|
+
<summary><b>Anything else</b></summary>
|
|
142
|
+
|
|
143
|
+
It's a standard stdio MCP server: run `uvx mrbilit-mcp`, or `pip install mrbilit-mcp` and run `mrbilit-mcp`.
|
|
144
|
+
</details>
|
|
145
|
+
|
|
146
|
+
Then just ask:
|
|
147
|
+
|
|
148
|
+
- "Cheapest day to fly Tehran to Kish in the next month, and the baggage on that flight?"
|
|
149
|
+
- "Train from Tehran to Mashhad next Friday for 2 adults and a child: which classes have seats and what's the total?"
|
|
150
|
+
- "4-star hotels in Shiraz for 3 nights from the 20th under 3 million Toman a night, with their reviews."
|
|
151
|
+
- <span dir="rtl">ارزان‌ترین اتوبوس VIP تهران به اصفهان فردا شب و صندلی‌های خالی آن؟</span>
|
|
152
|
+
|
|
153
|
+
## How it works
|
|
154
|
+
|
|
155
|
+
```text
|
|
156
|
+
AI agent (Claude, Cursor, Copilot, ...)
|
|
157
|
+
│
|
|
158
|
+
│ MCP over stdio
|
|
159
|
+
▼
|
|
160
|
+
mrbilit-mcp (runs on your machine)
|
|
161
|
+
│
|
|
162
|
+
│ HTTPS (REST, optional proxy)
|
|
163
|
+
├──────▶ flight.atighgasht.com, train.mrbilit.com, masir.mrbilit.com, bus.mrbilit.ir, hotel.mrbilit.ir
|
|
164
|
+
└──────▶ content.mrbilit.ir, directus.mrbilit.ir, mrbilit.com (site lists, magazine)
|
|
165
|
+
```
|
|
166
|
+
|
|
167
|
+
`mrbilit-mcp` runs locally and calls the same public endpoints the mrbilit.com website uses. There's no hosted
|
|
168
|
+
server in between, no API key, and nothing about you is sent anywhere else.
|
|
169
|
+
|
|
170
|
+
## Tools
|
|
171
|
+
|
|
172
|
+
Every search takes the codes from `mb_find_place`: IATA codes for flights (`THR`, `MHD`, `ISTALL`), station ids for
|
|
173
|
+
trains (Tehran `1`, Mashhad `191`), 8-digit city ids for buses and taxis (Tehran `11320000`), slugs for hotels
|
|
174
|
+
(`mashhad`, `mashhad/enghelab`).
|
|
175
|
+
|
|
176
|
+
<details open>
|
|
177
|
+
<summary><b>📍 Places and companies</b> (2)</summary>
|
|
178
|
+
|
|
179
|
+
| Tool | What it does |
|
|
180
|
+
|---|---|
|
|
181
|
+
| `mb_find_place` | City, airport, station or hotel name → the code each search takes (flight, train, bus, taxi, hotel) |
|
|
182
|
+
| `mb_companies` | Airlines, rail operators, bus companies and taxi classes with their codes |
|
|
183
|
+
</details>
|
|
184
|
+
|
|
185
|
+
<details open>
|
|
186
|
+
<summary><b>✈️ Flights</b> (3)</summary>
|
|
187
|
+
|
|
188
|
+
| Tool | What it does |
|
|
189
|
+
|---|---|
|
|
190
|
+
| `mb_search_flights` | Flights on a date, one-way or round trip, domestic or international: price per adult and party total, seats, baggage; cabin, airline, direct and time filters |
|
|
191
|
+
| `mb_flight_price_calendar` | Cheapest fare per day over up to 180 days |
|
|
192
|
+
| `mb_flight_fare_details` | One flight or round-trip package's fares: refund penalties, checked baggage, fare rules, notes, adult/child/infant prices |
|
|
193
|
+
</details>
|
|
194
|
+
|
|
195
|
+
<details open>
|
|
196
|
+
<summary><b>🚆 Trains</b> (5)</summary>
|
|
197
|
+
|
|
198
|
+
| Tool | What it does |
|
|
199
|
+
|---|---|
|
|
200
|
+
| `mb_search_trains` | Trains on a date with every class, price per adult and fresh free-seat counts; men/women/general/car quotas |
|
|
201
|
+
| `mb_train_price_calendar` | Cheapest bookable train per day |
|
|
202
|
+
| `mb_train_price` | Exact price of a class for adults, children, infants, foreigners and empty berths, with the total |
|
|
203
|
+
| `mb_train_stops` | Every stop of a train with date and time |
|
|
204
|
+
| `mb_alternative_routes` | Trips with one change (any mix of train and bus) and nearby train, bus and flight routes |
|
|
205
|
+
</details>
|
|
206
|
+
|
|
207
|
+
<details open>
|
|
208
|
+
<summary><b>🚌 Buses and taxis</b> (4)</summary>
|
|
209
|
+
|
|
210
|
+
| Tool | What it does |
|
|
211
|
+
|---|---|
|
|
212
|
+
| `mb_search_buses` | Buses on a date: company, terminal, times, price per seat, free seats, VIP, stops, refund penalties |
|
|
213
|
+
| `mb_bus_price_calendar` | Cheapest bus seat per day |
|
|
214
|
+
| `mb_bus_seats` | Seat map: free seats, seats sold to women and men, row layout with the aisle |
|
|
215
|
+
| `mb_search_taxis` | Private door-to-door intercity taxis, price per car, by class and pick-up slot |
|
|
216
|
+
</details>
|
|
217
|
+
|
|
218
|
+
<details open>
|
|
219
|
+
<summary><b>🏨 Hotels</b> (5)</summary>
|
|
220
|
+
|
|
221
|
+
| Tool | What it does |
|
|
222
|
+
|---|---|
|
|
223
|
+
| `mb_search_hotels` | Available hotels in a city for dates with the cheapest stay price; stars, type, price and refund filters |
|
|
224
|
+
| `mb_hotel` | One hotel: rating, latest reviews with per-criterion scores, location, landmarks, rules, amenities |
|
|
225
|
+
| `mb_hotel_rooms` | Every room with its exact price for the dates, per night, rooms left, meals |
|
|
226
|
+
| `mb_hotel_calendar` | Cheapest one-night price per night, up to ~48 nights ahead |
|
|
227
|
+
| `mb_city_hotels` | Every hotel of a city, sold out ones included, filtered by stars, type or name (no prices) |
|
|
228
|
+
</details>
|
|
229
|
+
|
|
230
|
+
<details open>
|
|
231
|
+
<summary><b>📢 Notices and help</b> (3)</summary>
|
|
232
|
+
|
|
233
|
+
| Tool | What it does |
|
|
234
|
+
|---|---|
|
|
235
|
+
| `mb_notices` | Notices MrBilit shows right now for a service or route |
|
|
236
|
+
| `mb_help` | Search the official rules, FAQ and help-center guides (refunds, baggage, auto-reserve, ...) |
|
|
237
|
+
| `mb_travel_guide` | Route or city guide (summary, FAQ, article) and travel-magazine posts |
|
|
238
|
+
</details>
|
|
239
|
+
|
|
240
|
+
All 22 tools are annotated `readOnlyHint: true` and return compact structured JSON, so they don't flood the agent's context.
|
|
241
|
+
|
|
242
|
+
## Good to know
|
|
243
|
+
|
|
244
|
+
- **Prices are in Toman** in every tool (the API sends Rial; values are divided by 10), always in fields named `*_toman`.
|
|
245
|
+
Flight `price_toman` is per adult and `total_toman` the whole party; trains per adult; buses per seat; taxis per car;
|
|
246
|
+
hotels the whole stay for one room.
|
|
247
|
+
- **Dates** in and out are Gregorian `YYYY-MM-DD`; past dates are rejected. Times are local to the place: a flight
|
|
248
|
+
time at a foreign airport is that airport's local time, although the API puts `+03:30` on every flight time.
|
|
249
|
+
- **Ratings are 0–5**; `null` means not rated. The site shows hotel ratings ×2 out of 10.
|
|
250
|
+
- **Ids expire**: `flight_id`, `class_id` and `bus_id` come from a fresh search.
|
|
251
|
+
- **Sales windows**: trains open about 18 days ahead, buses about a month. An empty result often just means "not on sale yet".
|
|
252
|
+
- **Round trips**: domestic flights are two separate tickets (two lists); international round trips are priced as one package.
|
|
253
|
+
- **Hotel prices do not depend on the guest count**: pick rooms whose `sleeps` fits, and add rooms up for a group.
|
|
254
|
+
- Domestic airports and train stations come from the site's own bundled lists, fetched once per run with a copy
|
|
255
|
+
shipped in the package as a fallback.
|
|
256
|
+
|
|
257
|
+
## FAQ
|
|
258
|
+
|
|
259
|
+
<details>
|
|
260
|
+
<summary><b>Do I need a proxy?</b></summary>
|
|
261
|
+
|
|
262
|
+
Usually not: direct calls from an Iranian connection work. If your network cannot reach MrBilit's API servers
|
|
263
|
+
(connections time out or are reset), set `MRBILIT_MCP_PROXY` to an HTTP proxy that can reach them.
|
|
264
|
+
System proxy variables (`HTTPS_PROXY`, ...) are ignored on purpose.
|
|
265
|
+
</details>
|
|
266
|
+
|
|
267
|
+
<details>
|
|
268
|
+
<summary><b>Can it book a ticket for me?</b></summary>
|
|
269
|
+
|
|
270
|
+
No, and that's deliberate. It has no login and never holds a seat, reserves, orders or pays. The agent finds the
|
|
271
|
+
best option; you book on mrbilit.com.
|
|
272
|
+
</details>
|
|
273
|
+
|
|
274
|
+
<details>
|
|
275
|
+
<summary><b>I get "did not answer in time" or "Could not reach"</b></summary>
|
|
276
|
+
|
|
277
|
+
The server retries a reset connection once. If it keeps failing, set `MRBILIT_MCP_PROXY` (see above). The one-change
|
|
278
|
+
trip search (`mb_alternative_routes`) is known to hang now and then; it is retried and its other parts are still returned.
|
|
279
|
+
</details>
|
|
280
|
+
|
|
281
|
+
<details>
|
|
282
|
+
<summary><b>Why does a sold-out train class still have a price in <code>mb_train_price</code>?</b></summary>
|
|
283
|
+
|
|
284
|
+
The pricing endpoint prices any class; availability comes from `mb_search_trains` (`seats_left`, `bookable`).
|
|
285
|
+
</details>
|
|
286
|
+
|
|
287
|
+
<details>
|
|
288
|
+
<summary><b>Claude Desktop says <code>uvx</code> is not found</b></summary>
|
|
289
|
+
|
|
290
|
+
Use the full path to `uvx` (`where uvx` on Windows, `which uvx` on macOS/Linux) as `command`.
|
|
291
|
+
</details>
|
|
292
|
+
|
|
293
|
+
<details>
|
|
294
|
+
<summary><b>How do I debug what the agent sees?</b></summary>
|
|
295
|
+
|
|
296
|
+
```bash
|
|
297
|
+
npx @modelcontextprotocol/inspector uvx mrbilit-mcp
|
|
298
|
+
```
|
|
299
|
+
</details>
|
|
300
|
+
|
|
301
|
+
## Configuration
|
|
302
|
+
|
|
303
|
+
| Variable | Default | Meaning |
|
|
304
|
+
|---|---|---|
|
|
305
|
+
| `MRBILIT_MCP_PROXY` | unset | HTTP proxy for every request, e.g. `http://user:pass@host:port`. Usually not needed in Iran |
|
|
306
|
+
|
|
307
|
+
## Safety
|
|
308
|
+
|
|
309
|
+
- Read-only: no login or OTP, no seat hold, reservation, order, payment, wallet, price alert or review posting.
|
|
310
|
+
The only POSTs are searches and price lookups the site itself makes before booking.
|
|
311
|
+
- Admin fields (`created_by`, `updated_by`) of the content CMS are never passed through.
|
|
312
|
+
- Always sends a browser User-Agent and at most two requests at a time, since the API hosts share one server.
|
|
313
|
+
|
|
314
|
+
## فارسی
|
|
315
|
+
|
|
316
|
+
<div dir="rtl">
|
|
317
|
+
|
|
318
|
+
**mrbilit-mcp** به دستیار هوش مصنوعی شما (Claude، Cursor، Copilot و ...) اجازه می‌دهد در مستربلیط ارزان‌ترین
|
|
319
|
+
پرواز، قطار، اتوبوس یا تاکسی دربستی را برای یک روز یا یک ماه پیدا کند، صندلی‌های خالی، بار مجاز و قوانین استرداد را ببیند
|
|
320
|
+
و هتل‌ها را با قیمت دقیق اتاق و نظرات مسافران مقایسه کند.
|
|
321
|
+
|
|
322
|
+
- فقط خواندنی است: وارد حساب نمی‌شود و صندلی رزرو یا بلیط صادر نمی‌کند.
|
|
323
|
+
- همه قیمت‌ها به تومان است.
|
|
324
|
+
- روی سیستم خود شما اجرا می‌شود و به هیچ سرور واسطی داده نمی‌فرستد.
|
|
325
|
+
- در ایران معمولاً نیازی به پروکسی نیست؛ اگر سرورهای مستربلیط پاسخ ندادند، `MRBILIT_MCP_PROXY` را تنظیم کنید.
|
|
326
|
+
|
|
327
|
+
**نصب در Claude Code:**
|
|
328
|
+
|
|
329
|
+
</div>
|
|
330
|
+
|
|
331
|
+
```bash
|
|
332
|
+
claude mcp add mrbilit -- uvx mrbilit-mcp
|
|
333
|
+
```
|
|
334
|
+
|
|
335
|
+
<div dir="rtl">
|
|
336
|
+
|
|
337
|
+
بعد بپرسید: «ارزان‌ترین راه رفتن از تهران به مشهد در ۲۸ مهر چیست؟»
|
|
338
|
+
|
|
339
|
+
</div>
|
|
340
|
+
|
|
341
|
+
## Development
|
|
342
|
+
|
|
343
|
+
```bash
|
|
344
|
+
git clone https://github.com/sepehr071/mrbilit-mcp && cd mrbilit-mcp
|
|
345
|
+
uv sync
|
|
346
|
+
uv run pytest # offline, against recorded responses
|
|
347
|
+
uv run pytest -m live # real API (set MRBILIT_MCP_PROXY if needed)
|
|
348
|
+
uv run ruff check .
|
|
349
|
+
```
|
|
350
|
+
|
|
351
|
+
Tools live in `src/mrbilit_mcp/places.py`, `flights.py`, `trains.py`, `buses.py`, `hotels.py` and `content.py`; each
|
|
352
|
+
is a typed async function with a docstring that tells the agent when to use it. Issues and PRs are welcome,
|
|
353
|
+
especially new tools and fixes for API changes.
|
|
354
|
+
|
|
355
|
+
Releases: bump the version in `pyproject.toml` and `server.json`, then push a `v*` tag. GitHub Actions tests,
|
|
356
|
+
publishes to PyPI and the [MCP Registry](https://registry.modelcontextprotocol.io), and creates the GitHub Release.
|
|
357
|
+
|
|
358
|
+
## Disclaimer
|
|
359
|
+
|
|
360
|
+
Unofficial and not affiliated with or endorsed by MrBilit. It uses the public endpoints of the mrbilit.com website,
|
|
361
|
+
which can change without notice. Please keep request rates reasonable.
|
|
362
|
+
|
|
363
|
+
## License
|
|
364
|
+
|
|
365
|
+
[MIT](https://github.com/sepehr071/mrbilit-mcp/blob/main/LICENSE)
|