khodro45-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.
- khodro45_mcp-0.1.0/.github/ISSUE_TEMPLATE/bug_report.yml +43 -0
- khodro45_mcp-0.1.0/.github/ISSUE_TEMPLATE/config.yml +5 -0
- khodro45_mcp-0.1.0/.github/banner.png +0 -0
- khodro45_mcp-0.1.0/.github/dependabot.yml +10 -0
- khodro45_mcp-0.1.0/.github/workflows/ci.yml +22 -0
- khodro45_mcp-0.1.0/.github/workflows/publish.yml +51 -0
- khodro45_mcp-0.1.0/.gitignore +6 -0
- khodro45_mcp-0.1.0/LICENSE +80 -0
- khodro45_mcp-0.1.0/PKG-INFO +157 -0
- khodro45_mcp-0.1.0/README.md +129 -0
- khodro45_mcp-0.1.0/pyproject.toml +56 -0
- khodro45_mcp-0.1.0/server.json +32 -0
- khodro45_mcp-0.1.0/src/khodro45_mcp/__init__.py +5 -0
- khodro45_mcp-0.1.0/src/khodro45_mcp/http.py +230 -0
- khodro45_mcp-0.1.0/src/khodro45_mcp/khodro45.py +491 -0
- khodro45_mcp-0.1.0/src/khodro45_mcp/registry.py +16 -0
- khodro45_mcp-0.1.0/src/khodro45_mcp/server.py +94 -0
- khodro45_mcp-0.1.0/tests/conftest.py +78 -0
- khodro45_mcp-0.1.0/tests/fixtures/brands.json +23 -0
- khodro45_mcp-0.1.0/tests/fixtures/cities.json +38 -0
- khodro45_mcp-0.1.0/tests/fixtures/colors.json +86 -0
- khodro45_mcp-0.1.0/tests/fixtures/detail.json +126 -0
- khodro45_mcp-0.1.0/tests/fixtures/listing.json +115 -0
- khodro45_mcp-0.1.0/tests/fixtures/models.json +106 -0
- khodro45_mcp-0.1.0/tests/fixtures/qc.json +318 -0
- khodro45_mcp-0.1.0/tests/fixtures/trims.json +16 -0
- khodro45_mcp-0.1.0/tests/fixtures/trimyears.json +18 -0
- khodro45_mcp-0.1.0/tests/fixtures/years.json +26 -0
- khodro45_mcp-0.1.0/tests/test_khodro45.py +240 -0
- khodro45_mcp-0.1.0/tests/test_live_khodro45.py +57 -0
- khodro45_mcp-0.1.0/uv.lock +1361 -0
|
@@ -0,0 +1,43 @@
|
|
|
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. k45_car
|
|
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. what khodro45.com shows for the same input
|
|
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
|
+
- Direct connection from Iran
|
|
36
|
+
- Direct connection outside Iran
|
|
37
|
+
- VPN or proxy
|
|
38
|
+
- KHODRO45_MCP_PROXY set
|
|
39
|
+
- type: input
|
|
40
|
+
id: version
|
|
41
|
+
attributes:
|
|
42
|
+
label: khodro45-mcp version
|
|
43
|
+
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/khodro45-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,80 @@
|
|
|
1
|
+
Required Notice: Copyright (c) 2026 Sepehr Radmard (https://github.com/sepehr071)
|
|
2
|
+
|
|
3
|
+
Free for personal and non-commercial use under the terms below. Commercial use needs a
|
|
4
|
+
separate license: contact Sepehr Radmard at https://www.linkedin.com/in/sepehr-radmard or https://github.com/sepehr071.
|
|
5
|
+
|
|
6
|
+
Versions released before this license change were published under the MIT license and stay under it.
|
|
7
|
+
|
|
8
|
+
# PolyForm Noncommercial License 1.0.0
|
|
9
|
+
|
|
10
|
+
<https://polyformproject.org/licenses/noncommercial/1.0.0>
|
|
11
|
+
|
|
12
|
+
## Acceptance
|
|
13
|
+
|
|
14
|
+
In order to get any license under these terms, you must agree to them as both strict obligations and conditions to all your licenses.
|
|
15
|
+
|
|
16
|
+
## Copyright License
|
|
17
|
+
|
|
18
|
+
The licensor grants you a copyright license for the software to do everything you might do with the software that would otherwise infringe the licensor's copyright in it for any permitted purpose. However, you may only distribute the software according to [Distribution License](#distribution-license) and make changes or new works based on the software according to [Changes and New Works License](#changes-and-new-works-license).
|
|
19
|
+
|
|
20
|
+
## Distribution License
|
|
21
|
+
|
|
22
|
+
The licensor grants you an additional copyright license to distribute copies of the software. Your license to distribute covers distributing the software with changes and new works permitted by [Changes and New Works License](#changes-and-new-works-license).
|
|
23
|
+
|
|
24
|
+
## Notices
|
|
25
|
+
|
|
26
|
+
You must ensure that anyone who gets a copy of any part of the software from you also gets a copy of these terms or the URL for them above, as well as copies of any plain-text lines beginning with `Required Notice:` that the licensor provided with the software. For example:
|
|
27
|
+
|
|
28
|
+
> Required Notice: Copyright Yoyodyne, Inc. (http://example.com)
|
|
29
|
+
|
|
30
|
+
## Changes and New Works License
|
|
31
|
+
|
|
32
|
+
The licensor grants you an additional copyright license to make changes and new works based on the software for any permitted purpose.
|
|
33
|
+
|
|
34
|
+
## Patent License
|
|
35
|
+
|
|
36
|
+
The licensor grants you a patent license for the software that covers patent claims the licensor can license, or becomes able to license, that you would infringe by using the software.
|
|
37
|
+
|
|
38
|
+
## Noncommercial Purposes
|
|
39
|
+
|
|
40
|
+
Any noncommercial purpose is a permitted purpose.
|
|
41
|
+
|
|
42
|
+
## Personal Uses
|
|
43
|
+
|
|
44
|
+
Personal use for research, experiment, and testing for the benefit of public knowledge, personal study, private entertainment, hobby projects, amateur pursuits, or religious observance, without any anticipated commercial application, is use for a permitted purpose.
|
|
45
|
+
|
|
46
|
+
## Noncommercial Organizations
|
|
47
|
+
|
|
48
|
+
Use by any charitable organization, educational institution, public research organization, public safety or health organization, environmental protection organization, or government institution is use for a permitted purpose regardless of the source of funding or obligations resulting from the funding.
|
|
49
|
+
|
|
50
|
+
## Fair Use
|
|
51
|
+
|
|
52
|
+
You may have "fair use" rights for the software under the law. These terms do not limit them.
|
|
53
|
+
|
|
54
|
+
## No Other Rights
|
|
55
|
+
|
|
56
|
+
These terms do not allow you to sublicense or transfer any of your licenses to anyone else, or prevent the licensor from granting licenses to anyone else. These terms do not imply any other licenses.
|
|
57
|
+
|
|
58
|
+
## Patent Defense
|
|
59
|
+
|
|
60
|
+
If you make any written claim that the software infringes or contributes to infringement of any patent, your patent license for the software granted under these terms ends immediately. If your company makes such a claim, your patent license ends immediately for work on behalf of your company.
|
|
61
|
+
|
|
62
|
+
## Violations
|
|
63
|
+
|
|
64
|
+
The first time you are notified in writing that you have violated any of these terms, or done anything with the software not covered by your licenses, your licenses can nonetheless continue if you come into full compliance with these terms, and take practical steps to correct past violations, within 32 days of receiving notice. Otherwise, all your licenses end immediately.
|
|
65
|
+
|
|
66
|
+
## No Liability
|
|
67
|
+
|
|
68
|
+
***As far as the law allows, the software comes as is, without any warranty or condition, and the licensor will not be liable to you for any damages arising out of these terms or the use or nature of the software, under any kind of legal claim.***
|
|
69
|
+
|
|
70
|
+
## Definitions
|
|
71
|
+
|
|
72
|
+
The **licensor** is the individual or entity offering these terms, and the **software** is the software the licensor makes available under these terms.
|
|
73
|
+
|
|
74
|
+
**You** refers to the individual or entity agreeing to these terms.
|
|
75
|
+
|
|
76
|
+
**Your company** is any legal entity, sole proprietorship, or other kind of organization that you work for, plus all organizations that have control over, are under the control of, or are under common control with that organization. **Control** means ownership of substantially all the assets of an entity, or the power to direct its management and policies by vote, contract, or otherwise. Control can be direct or indirect.
|
|
77
|
+
|
|
78
|
+
**Your licenses** are all the licenses granted to you for the software under these terms.
|
|
79
|
+
|
|
80
|
+
**Use** means anything you do with the software requiring one of your licenses.
|
|
@@ -0,0 +1,157 @@
|
|
|
1
|
+
Metadata-Version: 2.5
|
|
2
|
+
Name: khodro45-mcp
|
|
3
|
+
Version: 0.1.0
|
|
4
|
+
Summary: Unofficial read-only MCP server for Khodro45 (خودرو۴۵, khodro45.com), the Iranian used-car marketplace: listings, inspection reports, price estimate, sale prices.
|
|
5
|
+
Project-URL: Homepage, https://github.com/sepehr071/khodro45-mcp
|
|
6
|
+
Project-URL: Repository, https://github.com/sepehr071/khodro45-mcp
|
|
7
|
+
Project-URL: Issues, https://github.com/sepehr071/khodro45-mcp/issues
|
|
8
|
+
Project-URL: Website, https://mcpfarsi.ir/
|
|
9
|
+
Author-email: Sepehr Radmard <sepehrr80@gmail.com>
|
|
10
|
+
License-Expression: PolyForm-Noncommercial-1.0.0
|
|
11
|
+
License-File: LICENSE
|
|
12
|
+
Keywords: ai-agents,car-inspection,car-marketplace,car-price-estimate,cars,claude,farsi,iran,khodro-45,khodro45,khodro45-com,khodro45-mcp,mcp,mcp-server,model-context-protocol,persian,used-cars
|
|
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: curl-cffi>=0.16.3
|
|
24
|
+
Requires-Dist: httpx-curl-cffi>=0.1.5
|
|
25
|
+
Requires-Dist: httpx>=0.27
|
|
26
|
+
Requires-Dist: mcp<3,>=2.2
|
|
27
|
+
Description-Content-Type: text/markdown
|
|
28
|
+
|
|
29
|
+
<!-- mcp-name: io.github.sepehr071/khodro45-mcp -->
|
|
30
|
+
|
|
31
|
+
<div align="center">
|
|
32
|
+
|
|
33
|
+
<img src="https://raw.githubusercontent.com/sepehr071/khodro45-mcp/main/.github/banner.png" alt="khodro45-mcp: unofficial Khodro45 (خودرو۴۵) MCP server that estimates used-car prices, searches inspected cars for sale and reads inspection reports for Claude, Cursor and Copilot" width="100%">
|
|
34
|
+
|
|
35
|
+
# khodro45-mcp: Khodro45 (خودرو۴۵) Iranian used-car marketplace MCP server for AI agents
|
|
36
|
+
|
|
37
|
+
**khodro45-mcp is an unofficial, read-only MCP server that lets an AI agent estimate used-car prices, search inspected cars for sale, read listings and inspection reports, and see real sale prices on Khodro45 (خودرو۴۵, khodro45.com), an Iranian used-car marketplace.**<br>
|
|
38
|
+
Its 10 tools list brands, models, trims and years, give the public used-car price estimate, search the cars listed for sale, read one listing in full and its expert inspection report, list recent real sales and show zero-km market prices.<br>
|
|
39
|
+
No API key or Khodro45 account is needed; it works in Claude, Cursor, Copilot and any other MCP client.
|
|
40
|
+
|
|
41
|
+
[](https://pypi.org/project/khodro45-mcp/)
|
|
42
|
+
[](https://pypi.org/project/khodro45-mcp/)
|
|
43
|
+
[](https://github.com/sepehr071/khodro45-mcp/actions/workflows/ci.yml)
|
|
44
|
+
[](https://github.com/sepehr071/khodro45-mcp/blob/main/LICENSE)
|
|
45
|
+
|
|
46
|
+
[For AI agents](#for-ai-agents) · [Quick start](#quick-start) · [Tools](#tools) · [Limits](#limits) · [فارسی](#فارسی)
|
|
47
|
+
|
|
48
|
+
</div>
|
|
49
|
+
|
|
50
|
+
---
|
|
51
|
+
|
|
52
|
+
## For AI agents
|
|
53
|
+
|
|
54
|
+
- **What:** unofficial MCP server (model context protocol) for khodro45.com: the public used-car price estimate, inspected cars for sale, listing details, inspection reports, recent sales and zero-km market prices.
|
|
55
|
+
- **Install:** `uvx khodro45-mcp` or `claude mcp add khodro45 -- uvx khodro45-mcp`. Transport: stdio. Needs [uv](https://docs.astral.sh/uv/getting-started/installation/) (Python 3.10+).
|
|
56
|
+
- **Auth:** none. Optional `KHODRO45_MCP_PROXY` (HTTP proxy URL, or a comma-separated list); system proxy settings are ignored.
|
|
57
|
+
- **Access:** read-only. It cannot log in, book an inspection, sell a car or buy one. Seller names and phone numbers are never returned.
|
|
58
|
+
- **Tools:** 10, all prefixed `k45_`. Typical sequences: `k45_brands` -> `k45_models` -> `k45_trims` -> `k45_price_estimate`; `k45_cars` -> `k45_car` -> `k45_inspection`; `k45_deals` for what really sold.
|
|
59
|
+
- **Use when:** the user asks what a used car is worth, wants to find a used car in an Iranian city under a budget, wants a car's inspection report or defects, or asks what cars recently sold for.
|
|
60
|
+
- **Output:** compact JSON. Prices are Toman, mileage is km, years are Persian (Gregorian for imported cars). Names are Persian with English brand names where the site has them.
|
|
61
|
+
|
|
62
|
+
## Quick start
|
|
63
|
+
|
|
64
|
+
You need [uv](https://docs.astral.sh/uv/getting-started/installation/). No API key or account.
|
|
65
|
+
|
|
66
|
+
Claude Code:
|
|
67
|
+
|
|
68
|
+
```bash
|
|
69
|
+
claude mcp add khodro45 -- uvx khodro45-mcp
|
|
70
|
+
```
|
|
71
|
+
|
|
72
|
+
Claude Desktop, Cursor, VS Code and other clients:
|
|
73
|
+
|
|
74
|
+
```json
|
|
75
|
+
{
|
|
76
|
+
"mcpServers": {
|
|
77
|
+
"khodro45": { "command": "uvx", "args": ["khodro45-mcp"] }
|
|
78
|
+
}
|
|
79
|
+
}
|
|
80
|
+
```
|
|
81
|
+
|
|
82
|
+
Example prompts:
|
|
83
|
+
|
|
84
|
+
- "What is a Samand EF7 1396 with 150,000 km worth?"
|
|
85
|
+
- "Find the cheapest Peugeot 207 for sale in Tehran and show me its inspection report."
|
|
86
|
+
- "What did used Kia cars really sell for on Khodro45 lately?"
|
|
87
|
+
- <span dir="rtl">قیمت پژو ۲۰۷ مدل ۱۴۰۰ در تهران چقدر است؟</span>
|
|
88
|
+
- <span dir="rtl">گزارش کارشناسی این خودرو را نشان بده.</span>
|
|
89
|
+
|
|
90
|
+
Real answer (18 Nov 2026): `k45_price_estimate(trim_id=1849, year=1396, km=150000)` (Samand EF7) returned a market price of 1,570,000,000 Toman (range 1,511,000,000 to 1,628,000,000) and a Khodro45 offer of about 1,461,000,000 Toman. `k45_cars(brand="peugeot", model="207", city="تهران", sort="cheapest")` listed 112 cars, the cheapest at 1,818,000,000 Toman.
|
|
91
|
+
|
|
92
|
+
## Tools
|
|
93
|
+
|
|
94
|
+
| Tool | What it returns |
|
|
95
|
+
|---|---|
|
|
96
|
+
| `k45_brands` | Car brands, optionally filtered by name |
|
|
97
|
+
| `k45_models` | The models of one brand |
|
|
98
|
+
| `k45_trims` | The trims of a model and their model years |
|
|
99
|
+
| `k45_price_estimate` | Public used-car price estimate (market range and Khodro45's own price) for a trim, year and mileage |
|
|
100
|
+
| `k45_cities` | The cities with listings |
|
|
101
|
+
| `k45_cars` | Used cars for sale: filter by brand, model, city, price, year, km, gearbox, installments |
|
|
102
|
+
| `k45_car` | One listing in full: price, specs, document and ownership facts, photos |
|
|
103
|
+
| `k45_inspection` | The public expert inspection report: section scores and every found defect |
|
|
104
|
+
| `k45_deals` | Used cars Khodro45 really sold lately, with sale price, km, city and quality |
|
|
105
|
+
| `k45_new_car_prices` | Today's zero-km market, factory and dealer prices of a brand, or the market indexes |
|
|
106
|
+
|
|
107
|
+
## Limits
|
|
108
|
+
|
|
109
|
+
- The estimate is for a car with no defects (the public form sends none). Khodro45's own offer varies by about 1% between identical calls; the market price is stable.
|
|
110
|
+
- Card prices exclude the service fee; `price_toman` is the final price the page shows and `car_price_toman` the car's own price. The price filters apply to the car price.
|
|
111
|
+
- Listing pages are cached for a few minutes, so the site can lag the API by a few new listings.
|
|
112
|
+
- The city list has 87 cities; a few listings sit in smaller cities outside it, so `city` cannot filter those. Fuel type and seat colour are numeric codes with no public legend and are not exposed.
|
|
113
|
+
- The overall "health score" in `k45_inspection` is computed from the section scores (it is not in the API); it matched the page on the cars checked.
|
|
114
|
+
- Booking, selling, login and agent contact details are not covered. Khodro45 answered both Iranian and foreign networks in testing; if yours is blocked, set `KHODRO45_MCP_PROXY`.
|
|
115
|
+
|
|
116
|
+
## How it works
|
|
117
|
+
|
|
118
|
+
Khodro45 has no public API documentation. The endpoints were mapped by watching khodro45.com in Chrome, and every tool was then checked in Chrome against the real rendered pages (price wizard, listings, listing pages, inspection reports, cities, brands) on 18 Nov 2026. The server calls those same public endpoints through a Chrome-impersonating HTTP client, with a short cache and at most two requests at a time.
|
|
119
|
+
|
|
120
|
+
## فارسی
|
|
121
|
+
|
|
122
|
+
<div dir="rtl">
|
|
123
|
+
|
|
124
|
+
**khodro45-mcp** یک سرور MCP غیررسمی و فقطخواندنی برای خودرو۴۵ (khodro45.com) است. با آن یک عامل هوش مصنوعی میتواند برند، مدل و تیپ خودروها را ببیند، قیمت کارشناسی خودروی کارکرده را بر اساس سال و کارکرد تخمین بزند، خودروهای کارشناسیشدهٔ آگهیشده را جستوجو کند، جزئیات هر آگهی و گزارش کارشناسی آن را بخواند، قیمت فروش واقعی خودروهای اخیر و قیمت بازار خودروی صفر را ببیند. بدون حساب کاربری و کلید API کار میکند. نصب در Claude Code:
|
|
125
|
+
|
|
126
|
+
</div>
|
|
127
|
+
|
|
128
|
+
```bash
|
|
129
|
+
claude mcp add khodro45 -- uvx khodro45-mcp
|
|
130
|
+
```
|
|
131
|
+
|
|
132
|
+
## Development
|
|
133
|
+
|
|
134
|
+
```bash
|
|
135
|
+
uv sync
|
|
136
|
+
uv run ruff check . && uv run ruff format --check .
|
|
137
|
+
uv run python -m pytest -q # offline tests on recorded fixtures
|
|
138
|
+
uv run python -m pytest -m live -q # live calls to khodro45.com
|
|
139
|
+
```
|
|
140
|
+
|
|
141
|
+
Releases: bump the version in `pyproject.toml` and `server.json`, run `uv lock`, then push a `v*` tag; GitHub Actions publishes to PyPI.
|
|
142
|
+
|
|
143
|
+
## Disclaimer
|
|
144
|
+
|
|
145
|
+
Unofficial and not affiliated with or endorsed by Khodro45. It is read-only and uses the public pages and API of khodro45.com, which can change without notice.
|
|
146
|
+
|
|
147
|
+
## Author
|
|
148
|
+
|
|
149
|
+
Built and maintained by **Sepehr Radmard** (سپهر رادمرد). [LinkedIn](https://www.linkedin.com/in/sepehr-radmard) · [GitHub](https://github.com/sepehr071) · more servers in [iran-mcp](https://github.com/sepehr071/iran-mcp).
|
|
150
|
+
|
|
151
|
+
## مجوز استفاده (License)
|
|
152
|
+
|
|
153
|
+
<a href="https://www.linkedin.com/in/sepehr-radmard"><img src="https://raw.githubusercontent.com/sepehr071/iran-mcp/main/assets/license-banner.png" alt="استفادهٔ شخصی و غیرتجاری رایگان است؛ برای استفادهٔ تجاری با سپهر رادمرد تماس بگیرید. Free for personal and non-commercial use; commercial use needs a license." width="100%"></a>
|
|
154
|
+
|
|
155
|
+
**استفادهٔ شخصی و غیرتجاری رایگان است.** استفاده در شرکت، محصول پولی یا پروژهٔ مشتری به مجوز تجاری نیاز دارد؛ از راه [لینکدین](https://www.linkedin.com/in/sepehr-radmard) یا [گیت‌هاب](https://github.com/sepehr071) با سپهر رادمرد تماس بگیرید. متن کامل: [PolyForm Noncommercial 1.0.0](https://github.com/sepehr071/khodro45-mcp/blob/main/LICENSE).
|
|
156
|
+
|
|
157
|
+
Free for personal and non-commercial use under the [PolyForm Noncommercial License 1.0.0](https://github.com/sepehr071/khodro45-mcp/blob/main/LICENSE). Using it in a company, a paid product or a client project needs a commercial license: contact Sepehr Radmard on [LinkedIn](https://www.linkedin.com/in/sepehr-radmard) or [GitHub](https://github.com/sepehr071).
|
|
@@ -0,0 +1,129 @@
|
|
|
1
|
+
<!-- mcp-name: io.github.sepehr071/khodro45-mcp -->
|
|
2
|
+
|
|
3
|
+
<div align="center">
|
|
4
|
+
|
|
5
|
+
<img src="https://raw.githubusercontent.com/sepehr071/khodro45-mcp/main/.github/banner.png" alt="khodro45-mcp: unofficial Khodro45 (خودرو۴۵) MCP server that estimates used-car prices, searches inspected cars for sale and reads inspection reports for Claude, Cursor and Copilot" width="100%">
|
|
6
|
+
|
|
7
|
+
# khodro45-mcp: Khodro45 (خودرو۴۵) Iranian used-car marketplace MCP server for AI agents
|
|
8
|
+
|
|
9
|
+
**khodro45-mcp is an unofficial, read-only MCP server that lets an AI agent estimate used-car prices, search inspected cars for sale, read listings and inspection reports, and see real sale prices on Khodro45 (خودرو۴۵, khodro45.com), an Iranian used-car marketplace.**<br>
|
|
10
|
+
Its 10 tools list brands, models, trims and years, give the public used-car price estimate, search the cars listed for sale, read one listing in full and its expert inspection report, list recent real sales and show zero-km market prices.<br>
|
|
11
|
+
No API key or Khodro45 account is needed; it works in Claude, Cursor, Copilot and any other MCP client.
|
|
12
|
+
|
|
13
|
+
[](https://pypi.org/project/khodro45-mcp/)
|
|
14
|
+
[](https://pypi.org/project/khodro45-mcp/)
|
|
15
|
+
[](https://github.com/sepehr071/khodro45-mcp/actions/workflows/ci.yml)
|
|
16
|
+
[](https://github.com/sepehr071/khodro45-mcp/blob/main/LICENSE)
|
|
17
|
+
|
|
18
|
+
[For AI agents](#for-ai-agents) · [Quick start](#quick-start) · [Tools](#tools) · [Limits](#limits) · [فارسی](#فارسی)
|
|
19
|
+
|
|
20
|
+
</div>
|
|
21
|
+
|
|
22
|
+
---
|
|
23
|
+
|
|
24
|
+
## For AI agents
|
|
25
|
+
|
|
26
|
+
- **What:** unofficial MCP server (model context protocol) for khodro45.com: the public used-car price estimate, inspected cars for sale, listing details, inspection reports, recent sales and zero-km market prices.
|
|
27
|
+
- **Install:** `uvx khodro45-mcp` or `claude mcp add khodro45 -- uvx khodro45-mcp`. Transport: stdio. Needs [uv](https://docs.astral.sh/uv/getting-started/installation/) (Python 3.10+).
|
|
28
|
+
- **Auth:** none. Optional `KHODRO45_MCP_PROXY` (HTTP proxy URL, or a comma-separated list); system proxy settings are ignored.
|
|
29
|
+
- **Access:** read-only. It cannot log in, book an inspection, sell a car or buy one. Seller names and phone numbers are never returned.
|
|
30
|
+
- **Tools:** 10, all prefixed `k45_`. Typical sequences: `k45_brands` -> `k45_models` -> `k45_trims` -> `k45_price_estimate`; `k45_cars` -> `k45_car` -> `k45_inspection`; `k45_deals` for what really sold.
|
|
31
|
+
- **Use when:** the user asks what a used car is worth, wants to find a used car in an Iranian city under a budget, wants a car's inspection report or defects, or asks what cars recently sold for.
|
|
32
|
+
- **Output:** compact JSON. Prices are Toman, mileage is km, years are Persian (Gregorian for imported cars). Names are Persian with English brand names where the site has them.
|
|
33
|
+
|
|
34
|
+
## Quick start
|
|
35
|
+
|
|
36
|
+
You need [uv](https://docs.astral.sh/uv/getting-started/installation/). No API key or account.
|
|
37
|
+
|
|
38
|
+
Claude Code:
|
|
39
|
+
|
|
40
|
+
```bash
|
|
41
|
+
claude mcp add khodro45 -- uvx khodro45-mcp
|
|
42
|
+
```
|
|
43
|
+
|
|
44
|
+
Claude Desktop, Cursor, VS Code and other clients:
|
|
45
|
+
|
|
46
|
+
```json
|
|
47
|
+
{
|
|
48
|
+
"mcpServers": {
|
|
49
|
+
"khodro45": { "command": "uvx", "args": ["khodro45-mcp"] }
|
|
50
|
+
}
|
|
51
|
+
}
|
|
52
|
+
```
|
|
53
|
+
|
|
54
|
+
Example prompts:
|
|
55
|
+
|
|
56
|
+
- "What is a Samand EF7 1396 with 150,000 km worth?"
|
|
57
|
+
- "Find the cheapest Peugeot 207 for sale in Tehran and show me its inspection report."
|
|
58
|
+
- "What did used Kia cars really sell for on Khodro45 lately?"
|
|
59
|
+
- <span dir="rtl">قیمت پژو ۲۰۷ مدل ۱۴۰۰ در تهران چقدر است؟</span>
|
|
60
|
+
- <span dir="rtl">گزارش کارشناسی این خودرو را نشان بده.</span>
|
|
61
|
+
|
|
62
|
+
Real answer (18 Nov 2026): `k45_price_estimate(trim_id=1849, year=1396, km=150000)` (Samand EF7) returned a market price of 1,570,000,000 Toman (range 1,511,000,000 to 1,628,000,000) and a Khodro45 offer of about 1,461,000,000 Toman. `k45_cars(brand="peugeot", model="207", city="تهران", sort="cheapest")` listed 112 cars, the cheapest at 1,818,000,000 Toman.
|
|
63
|
+
|
|
64
|
+
## Tools
|
|
65
|
+
|
|
66
|
+
| Tool | What it returns |
|
|
67
|
+
|---|---|
|
|
68
|
+
| `k45_brands` | Car brands, optionally filtered by name |
|
|
69
|
+
| `k45_models` | The models of one brand |
|
|
70
|
+
| `k45_trims` | The trims of a model and their model years |
|
|
71
|
+
| `k45_price_estimate` | Public used-car price estimate (market range and Khodro45's own price) for a trim, year and mileage |
|
|
72
|
+
| `k45_cities` | The cities with listings |
|
|
73
|
+
| `k45_cars` | Used cars for sale: filter by brand, model, city, price, year, km, gearbox, installments |
|
|
74
|
+
| `k45_car` | One listing in full: price, specs, document and ownership facts, photos |
|
|
75
|
+
| `k45_inspection` | The public expert inspection report: section scores and every found defect |
|
|
76
|
+
| `k45_deals` | Used cars Khodro45 really sold lately, with sale price, km, city and quality |
|
|
77
|
+
| `k45_new_car_prices` | Today's zero-km market, factory and dealer prices of a brand, or the market indexes |
|
|
78
|
+
|
|
79
|
+
## Limits
|
|
80
|
+
|
|
81
|
+
- The estimate is for a car with no defects (the public form sends none). Khodro45's own offer varies by about 1% between identical calls; the market price is stable.
|
|
82
|
+
- Card prices exclude the service fee; `price_toman` is the final price the page shows and `car_price_toman` the car's own price. The price filters apply to the car price.
|
|
83
|
+
- Listing pages are cached for a few minutes, so the site can lag the API by a few new listings.
|
|
84
|
+
- The city list has 87 cities; a few listings sit in smaller cities outside it, so `city` cannot filter those. Fuel type and seat colour are numeric codes with no public legend and are not exposed.
|
|
85
|
+
- The overall "health score" in `k45_inspection` is computed from the section scores (it is not in the API); it matched the page on the cars checked.
|
|
86
|
+
- Booking, selling, login and agent contact details are not covered. Khodro45 answered both Iranian and foreign networks in testing; if yours is blocked, set `KHODRO45_MCP_PROXY`.
|
|
87
|
+
|
|
88
|
+
## How it works
|
|
89
|
+
|
|
90
|
+
Khodro45 has no public API documentation. The endpoints were mapped by watching khodro45.com in Chrome, and every tool was then checked in Chrome against the real rendered pages (price wizard, listings, listing pages, inspection reports, cities, brands) on 18 Nov 2026. The server calls those same public endpoints through a Chrome-impersonating HTTP client, with a short cache and at most two requests at a time.
|
|
91
|
+
|
|
92
|
+
## فارسی
|
|
93
|
+
|
|
94
|
+
<div dir="rtl">
|
|
95
|
+
|
|
96
|
+
**khodro45-mcp** یک سرور MCP غیررسمی و فقطخواندنی برای خودرو۴۵ (khodro45.com) است. با آن یک عامل هوش مصنوعی میتواند برند، مدل و تیپ خودروها را ببیند، قیمت کارشناسی خودروی کارکرده را بر اساس سال و کارکرد تخمین بزند، خودروهای کارشناسیشدهٔ آگهیشده را جستوجو کند، جزئیات هر آگهی و گزارش کارشناسی آن را بخواند، قیمت فروش واقعی خودروهای اخیر و قیمت بازار خودروی صفر را ببیند. بدون حساب کاربری و کلید API کار میکند. نصب در Claude Code:
|
|
97
|
+
|
|
98
|
+
</div>
|
|
99
|
+
|
|
100
|
+
```bash
|
|
101
|
+
claude mcp add khodro45 -- uvx khodro45-mcp
|
|
102
|
+
```
|
|
103
|
+
|
|
104
|
+
## Development
|
|
105
|
+
|
|
106
|
+
```bash
|
|
107
|
+
uv sync
|
|
108
|
+
uv run ruff check . && uv run ruff format --check .
|
|
109
|
+
uv run python -m pytest -q # offline tests on recorded fixtures
|
|
110
|
+
uv run python -m pytest -m live -q # live calls to khodro45.com
|
|
111
|
+
```
|
|
112
|
+
|
|
113
|
+
Releases: bump the version in `pyproject.toml` and `server.json`, run `uv lock`, then push a `v*` tag; GitHub Actions publishes to PyPI.
|
|
114
|
+
|
|
115
|
+
## Disclaimer
|
|
116
|
+
|
|
117
|
+
Unofficial and not affiliated with or endorsed by Khodro45. It is read-only and uses the public pages and API of khodro45.com, which can change without notice.
|
|
118
|
+
|
|
119
|
+
## Author
|
|
120
|
+
|
|
121
|
+
Built and maintained by **Sepehr Radmard** (سپهر رادمرد). [LinkedIn](https://www.linkedin.com/in/sepehr-radmard) · [GitHub](https://github.com/sepehr071) · more servers in [iran-mcp](https://github.com/sepehr071/iran-mcp).
|
|
122
|
+
|
|
123
|
+
## مجوز استفاده (License)
|
|
124
|
+
|
|
125
|
+
<a href="https://www.linkedin.com/in/sepehr-radmard"><img src="https://raw.githubusercontent.com/sepehr071/iran-mcp/main/assets/license-banner.png" alt="استفادهٔ شخصی و غیرتجاری رایگان است؛ برای استفادهٔ تجاری با سپهر رادمرد تماس بگیرید. Free for personal and non-commercial use; commercial use needs a license." width="100%"></a>
|
|
126
|
+
|
|
127
|
+
**استفادهٔ شخصی و غیرتجاری رایگان است.** استفاده در شرکت، محصول پولی یا پروژهٔ مشتری به مجوز تجاری نیاز دارد؛ از راه [لینکدین](https://www.linkedin.com/in/sepehr-radmard) یا [گیت‌هاب](https://github.com/sepehr071) با سپهر رادمرد تماس بگیرید. متن کامل: [PolyForm Noncommercial 1.0.0](https://github.com/sepehr071/khodro45-mcp/blob/main/LICENSE).
|
|
128
|
+
|
|
129
|
+
Free for personal and non-commercial use under the [PolyForm Noncommercial License 1.0.0](https://github.com/sepehr071/khodro45-mcp/blob/main/LICENSE). Using it in a company, a paid product or a client project needs a commercial license: contact Sepehr Radmard on [LinkedIn](https://www.linkedin.com/in/sepehr-radmard) or [GitHub](https://github.com/sepehr071).
|
|
@@ -0,0 +1,56 @@
|
|
|
1
|
+
[project]
|
|
2
|
+
name = "khodro45-mcp"
|
|
3
|
+
version = "0.1.0"
|
|
4
|
+
description = "Unofficial read-only MCP server for Khodro45 (خودرو۴۵, khodro45.com), the Iranian used-car marketplace: listings, inspection reports, price estimate, sale prices."
|
|
5
|
+
readme = "README.md"
|
|
6
|
+
license = "PolyForm-Noncommercial-1.0.0"
|
|
7
|
+
license-files = ["LICENSE"]
|
|
8
|
+
authors = [{ name = "Sepehr Radmard", email = "sepehrr80@gmail.com" }]
|
|
9
|
+
requires-python = ">=3.10"
|
|
10
|
+
keywords = ["mcp", "model-context-protocol", "khodro45", "khodro45-com", "khodro45-mcp", "khodro-45", "iran", "used-cars", "cars", "car-price-estimate", "car-inspection", "car-marketplace", "persian", "farsi", "claude", "ai-agents", "mcp-server"]
|
|
11
|
+
classifiers = [
|
|
12
|
+
"Development Status :: 4 - Beta",
|
|
13
|
+
"Intended Audience :: Developers",
|
|
14
|
+
"Operating System :: OS Independent",
|
|
15
|
+
"Programming Language :: Python :: 3",
|
|
16
|
+
"Programming Language :: Python :: 3.10",
|
|
17
|
+
"Programming Language :: Python :: 3.11",
|
|
18
|
+
"Programming Language :: Python :: 3.12",
|
|
19
|
+
"Programming Language :: Python :: 3.13",
|
|
20
|
+
"Topic :: Scientific/Engineering :: Artificial Intelligence",
|
|
21
|
+
]
|
|
22
|
+
dependencies = [
|
|
23
|
+
"mcp>=2.2,<3",
|
|
24
|
+
"httpx>=0.27",
|
|
25
|
+
"httpx-curl-cffi>=0.1.5",
|
|
26
|
+
"curl-cffi>=0.16.3",
|
|
27
|
+
]
|
|
28
|
+
|
|
29
|
+
[project.urls]
|
|
30
|
+
Homepage = "https://github.com/sepehr071/khodro45-mcp"
|
|
31
|
+
Repository = "https://github.com/sepehr071/khodro45-mcp"
|
|
32
|
+
Issues = "https://github.com/sepehr071/khodro45-mcp/issues"
|
|
33
|
+
Website = "https://mcpfarsi.ir/"
|
|
34
|
+
|
|
35
|
+
[project.scripts]
|
|
36
|
+
khodro45-mcp = "khodro45_mcp.server:main"
|
|
37
|
+
|
|
38
|
+
[dependency-groups]
|
|
39
|
+
dev = ["pytest>=8", "ruff>=0.6"]
|
|
40
|
+
|
|
41
|
+
[build-system]
|
|
42
|
+
requires = ["hatchling"]
|
|
43
|
+
build-backend = "hatchling.build"
|
|
44
|
+
|
|
45
|
+
[tool.pytest.ini_options]
|
|
46
|
+
testpaths = ["tests"]
|
|
47
|
+
addopts = "-m 'not live'"
|
|
48
|
+
markers = ["live: calls the real Khodro45 API (run with -m live)"]
|
|
49
|
+
|
|
50
|
+
[tool.ruff]
|
|
51
|
+
line-length = 120
|
|
52
|
+
target-version = "py310"
|
|
53
|
+
|
|
54
|
+
[tool.ruff.lint]
|
|
55
|
+
select = ["E", "F", "I", "B", "UP"]
|
|
56
|
+
ignore = ["E501"] # long Field(description=...) strings read better on one line
|
|
@@ -0,0 +1,32 @@
|
|
|
1
|
+
{
|
|
2
|
+
"$schema": "https://static.modelcontextprotocol.io/schemas/2025-12-11/server.schema.json",
|
|
3
|
+
"name": "io.github.sepehr071/khodro45-mcp",
|
|
4
|
+
"title": "Khodro45 Used Cars",
|
|
5
|
+
"description": "Read-only Khodro45 (khodro45.com) Iran used cars: listings, inspection reports, price estimate.",
|
|
6
|
+
"repository": {
|
|
7
|
+
"url": "https://github.com/sepehr071/khodro45-mcp",
|
|
8
|
+
"source": "github"
|
|
9
|
+
},
|
|
10
|
+
"websiteUrl": "https://github.com/sepehr071/khodro45-mcp",
|
|
11
|
+
"version": "0.1.0",
|
|
12
|
+
"packages": [
|
|
13
|
+
{
|
|
14
|
+
"registryType": "pypi",
|
|
15
|
+
"registryBaseUrl": "https://pypi.org",
|
|
16
|
+
"identifier": "khodro45-mcp",
|
|
17
|
+
"version": "0.1.0",
|
|
18
|
+
"runtimeHint": "uvx",
|
|
19
|
+
"transport": {
|
|
20
|
+
"type": "stdio"
|
|
21
|
+
},
|
|
22
|
+
"environmentVariables": [
|
|
23
|
+
{
|
|
24
|
+
"name": "KHODRO45_MCP_PROXY",
|
|
25
|
+
"description": "Optional HTTP proxy URL for the Khodro45 requests; system proxy settings are ignored. Also accepts a comma-separated list: one is used until it gets blocked or fails to connect, then the next.",
|
|
26
|
+
"isRequired": false,
|
|
27
|
+
"isSecret": false
|
|
28
|
+
}
|
|
29
|
+
]
|
|
30
|
+
}
|
|
31
|
+
]
|
|
32
|
+
}
|