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.
Files changed (31) hide show
  1. khodro45_mcp-0.1.0/.github/ISSUE_TEMPLATE/bug_report.yml +43 -0
  2. khodro45_mcp-0.1.0/.github/ISSUE_TEMPLATE/config.yml +5 -0
  3. khodro45_mcp-0.1.0/.github/banner.png +0 -0
  4. khodro45_mcp-0.1.0/.github/dependabot.yml +10 -0
  5. khodro45_mcp-0.1.0/.github/workflows/ci.yml +22 -0
  6. khodro45_mcp-0.1.0/.github/workflows/publish.yml +51 -0
  7. khodro45_mcp-0.1.0/.gitignore +6 -0
  8. khodro45_mcp-0.1.0/LICENSE +80 -0
  9. khodro45_mcp-0.1.0/PKG-INFO +157 -0
  10. khodro45_mcp-0.1.0/README.md +129 -0
  11. khodro45_mcp-0.1.0/pyproject.toml +56 -0
  12. khodro45_mcp-0.1.0/server.json +32 -0
  13. khodro45_mcp-0.1.0/src/khodro45_mcp/__init__.py +5 -0
  14. khodro45_mcp-0.1.0/src/khodro45_mcp/http.py +230 -0
  15. khodro45_mcp-0.1.0/src/khodro45_mcp/khodro45.py +491 -0
  16. khodro45_mcp-0.1.0/src/khodro45_mcp/registry.py +16 -0
  17. khodro45_mcp-0.1.0/src/khodro45_mcp/server.py +94 -0
  18. khodro45_mcp-0.1.0/tests/conftest.py +78 -0
  19. khodro45_mcp-0.1.0/tests/fixtures/brands.json +23 -0
  20. khodro45_mcp-0.1.0/tests/fixtures/cities.json +38 -0
  21. khodro45_mcp-0.1.0/tests/fixtures/colors.json +86 -0
  22. khodro45_mcp-0.1.0/tests/fixtures/detail.json +126 -0
  23. khodro45_mcp-0.1.0/tests/fixtures/listing.json +115 -0
  24. khodro45_mcp-0.1.0/tests/fixtures/models.json +106 -0
  25. khodro45_mcp-0.1.0/tests/fixtures/qc.json +318 -0
  26. khodro45_mcp-0.1.0/tests/fixtures/trims.json +16 -0
  27. khodro45_mcp-0.1.0/tests/fixtures/trimyears.json +18 -0
  28. khodro45_mcp-0.1.0/tests/fixtures/years.json +26 -0
  29. khodro45_mcp-0.1.0/tests/test_khodro45.py +240 -0
  30. khodro45_mcp-0.1.0/tests/test_live_khodro45.py +57 -0
  31. 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"
@@ -0,0 +1,5 @@
1
+ blank_issues_enabled: true
2
+ contact_links:
3
+ - name: Question or idea
4
+ url: https://github.com/sepehr071/khodro45-mcp/discussions
5
+ about: Ask how to use it or suggest a new tool
Binary file
@@ -0,0 +1,10 @@
1
+ version: 2
2
+ updates:
3
+ - package-ecosystem: github-actions
4
+ directory: /
5
+ schedule:
6
+ interval: monthly
7
+ - package-ecosystem: uv
8
+ directory: /
9
+ schedule:
10
+ interval: monthly
@@ -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,6 @@
1
+ .venv/
2
+ __pycache__/
3
+ *.pyc
4
+ dist/
5
+ .pytest_cache/
6
+ .ruff_cache/
@@ -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
+ [![PyPI](https://img.shields.io/pypi/v/khodro45-mcp?color=2563eb)](https://pypi.org/project/khodro45-mcp/)
42
+ [![Python](https://img.shields.io/pypi/pyversions/khodro45-mcp)](https://pypi.org/project/khodro45-mcp/)
43
+ [![CI](https://github.com/sepehr071/khodro45-mcp/actions/workflows/ci.yml/badge.svg)](https://github.com/sepehr071/khodro45-mcp/actions/workflows/ci.yml)
44
+ [![License: PolyForm Noncommercial](https://img.shields.io/badge/license-PolyForm%20Noncommercial-c2410c)](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) یا [گیت&zwnj;هاب](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
+ [![PyPI](https://img.shields.io/pypi/v/khodro45-mcp?color=2563eb)](https://pypi.org/project/khodro45-mcp/)
14
+ [![Python](https://img.shields.io/pypi/pyversions/khodro45-mcp)](https://pypi.org/project/khodro45-mcp/)
15
+ [![CI](https://github.com/sepehr071/khodro45-mcp/actions/workflows/ci.yml/badge.svg)](https://github.com/sepehr071/khodro45-mcp/actions/workflows/ci.yml)
16
+ [![License: PolyForm Noncommercial](https://img.shields.io/badge/license-PolyForm%20Noncommercial-c2410c)](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) یا [گیت&zwnj;هاب](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
+ }
@@ -0,0 +1,5 @@
1
+ """Unofficial MCP server for Khodro45 (khodro45.com): used-car listings, inspection reports, price estimates."""
2
+
3
+ from importlib.metadata import version
4
+
5
+ __version__ = version("khodro45-mcp")