varzesh3-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 (58) hide show
  1. varzesh3_mcp-0.1.0/.github/workflows/ci.yml +22 -0
  2. varzesh3_mcp-0.1.0/.github/workflows/publish.yml +51 -0
  3. varzesh3_mcp-0.1.0/.gitignore +6 -0
  4. varzesh3_mcp-0.1.0/LICENSE +21 -0
  5. varzesh3_mcp-0.1.0/PKG-INFO +162 -0
  6. varzesh3_mcp-0.1.0/README.md +135 -0
  7. varzesh3_mcp-0.1.0/pyproject.toml +55 -0
  8. varzesh3_mcp-0.1.0/server.json +32 -0
  9. varzesh3_mcp-0.1.0/src/varzesh3_mcp/__init__.py +5 -0
  10. varzesh3_mcp-0.1.0/src/varzesh3_mcp/http.py +230 -0
  11. varzesh3_mcp-0.1.0/src/varzesh3_mcp/registry.py +16 -0
  12. varzesh3_mcp-0.1.0/src/varzesh3_mcp/server.py +98 -0
  13. varzesh3_mcp-0.1.0/src/varzesh3_mcp/sports.py +1141 -0
  14. varzesh3_mcp-0.1.0/tests/conftest.py +78 -0
  15. varzesh3_mcp-0.1.0/tests/fixtures/archive_6.json +1 -0
  16. varzesh3_mcp-0.1.0/tests/fixtures/contents_wrestling.json +37 -0
  17. varzesh3_mcp-0.1.0/tests/fixtures/league_22.json +1 -0
  18. varzesh3_mcp-0.1.0/tests/fixtures/league_28.json +1 -0
  19. varzesh3_mcp-0.1.0/tests/fixtures/league_6.json +1 -0
  20. varzesh3_mcp-0.1.0/tests/fixtures/league_volleyball_33.json +85 -0
  21. varzesh3_mcp-0.1.0/tests/fixtures/leagues.json +1 -0
  22. varzesh3_mcp-0.1.0/tests/fixtures/live_schedule.json +33 -0
  23. varzesh3_mcp-0.1.0/tests/fixtures/livescore_today.json +1 -0
  24. varzesh3_mcp-0.1.0/tests/fixtures/match_basketball.json +1 -0
  25. varzesh3_mcp-0.1.0/tests/fixtures/match_football.json +1 -0
  26. varzesh3_mcp-0.1.0/tests/fixtures/match_var_441601.json +781 -0
  27. varzesh3_mcp-0.1.0/tests/fixtures/match_volleyball.json +90 -0
  28. varzesh3_mcp-0.1.0/tests/fixtures/matches_6.json +1 -0
  29. varzesh3_mcp-0.1.0/tests/fixtures/multi_28.json +1 -0
  30. varzesh3_mcp-0.1.0/tests/fixtures/multi_volleyball.json +82 -0
  31. varzesh3_mcp-0.1.0/tests/fixtures/news_article.json +1 -0
  32. varzesh3_mcp-0.1.0/tests/fixtures/news_latest.json +1 -0
  33. varzesh3_mcp-0.1.0/tests/fixtures/news_team.json +1 -0
  34. varzesh3_mcp-0.1.0/tests/fixtures/player_110789.json +40 -0
  35. varzesh3_mcp-0.1.0/tests/fixtures/player_110789_glance.json +110 -0
  36. varzesh3_mcp-0.1.0/tests/fixtures/playoffs_22.json +1 -0
  37. varzesh3_mcp-0.1.0/tests/fixtures/pred_497496.json +52 -0
  38. varzesh3_mcp-0.1.0/tests/fixtures/records_6.json +26 -0
  39. varzesh3_mcp-0.1.0/tests/fixtures/results_6.json +1 -0
  40. varzesh3_mcp-0.1.0/tests/fixtures/scorers_6.json +1 -0
  41. varzesh3_mcp-0.1.0/tests/fixtures/search.json +1 -0
  42. varzesh3_mcp-0.1.0/tests/fixtures/sidebar_stats_6.json +39 -0
  43. varzesh3_mcp-0.1.0/tests/fixtures/squad_6.json +1 -0
  44. varzesh3_mcp-0.1.0/tests/fixtures/standing_6.json +1 -0
  45. varzesh3_mcp-0.1.0/tests/fixtures/team_6.json +1 -0
  46. varzesh3_mcp-0.1.0/tests/fixtures/team_boxes_6.json +182 -0
  47. varzesh3_mcp-0.1.0/tests/fixtures/team_fixtures_6.json +1 -0
  48. varzesh3_mcp-0.1.0/tests/fixtures/team_possession_6.json +38 -0
  49. varzesh3_mcp-0.1.0/tests/fixtures/team_results_6.json +1 -0
  50. varzesh3_mcp-0.1.0/tests/fixtures/team_stats_goals.json +102 -0
  51. varzesh3_mcp-0.1.0/tests/fixtures/team_stats_leagues.json +50 -0
  52. varzesh3_mcp-0.1.0/tests/fixtures/team_stats_seasons.json +20 -0
  53. varzesh3_mcp-0.1.0/tests/fixtures/transfers_6.json +1 -0
  54. varzesh3_mcp-0.1.0/tests/fixtures/transfers_iran.json +320 -0
  55. varzesh3_mcp-0.1.0/tests/fixtures/videos.json +1 -0
  56. varzesh3_mcp-0.1.0/tests/test_live_varzesh3.py +121 -0
  57. varzesh3_mcp-0.1.0/tests/test_varzesh3.py +299 -0
  58. varzesh3_mcp-0.1.0/uv.lock +1362 -0
@@ -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/varzesh3-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,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2026 Sepehr Radmard
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,162 @@
1
+ Metadata-Version: 2.5
2
+ Name: varzesh3-mcp
3
+ Version: 0.1.0
4
+ Summary: Unofficial read-only MCP server for Varzesh3 (varzesh3.com), the Iranian sports site: live scores, tables, fixtures, teams, top scorers, news.
5
+ Project-URL: Homepage, https://github.com/sepehr071/varzesh3-mcp
6
+ Project-URL: Issues, https://github.com/sepehr071/varzesh3-mcp/issues
7
+ Project-URL: Website, https://mcpfarsi.ir/
8
+ Author-email: Sepehr Radmard <sepehrr80@gmail.com>
9
+ License-Expression: MIT
10
+ License-File: LICENSE
11
+ Keywords: claude,football,iran,livescore,mcp,model-context-protocol,persian,persian-gulf-pro-league,sports,standings,varzesh-3,varzesh3
12
+ Classifier: Development Status :: 4 - Beta
13
+ Classifier: Intended Audience :: Developers
14
+ Classifier: Operating System :: OS Independent
15
+ Classifier: Programming Language :: Python :: 3
16
+ Classifier: Programming Language :: Python :: 3.10
17
+ Classifier: Programming Language :: Python :: 3.11
18
+ Classifier: Programming Language :: Python :: 3.12
19
+ Classifier: Programming Language :: Python :: 3.13
20
+ Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
21
+ Requires-Python: >=3.10
22
+ Requires-Dist: curl-cffi>=0.16.3
23
+ Requires-Dist: httpx-curl-cffi>=0.1.5
24
+ Requires-Dist: httpx>=0.27
25
+ Requires-Dist: mcp<3,>=2.2
26
+ Description-Content-Type: text/markdown
27
+
28
+ <!-- mcp-name: io.github.sepehr071/varzesh3-mcp -->
29
+
30
+ <div align="center">
31
+
32
+ # varzesh3-mcp: Varzesh3 (ورزش سه) Iranian sports MCP server for AI agents
33
+
34
+ **varzesh3-mcp is an unofficial, read-only MCP server that gives AI agents the data of Varzesh3 (varzesh3.com), the biggest Iranian sports site.**<br>
35
+ Its 18 tools read live scores, match details with goals, cards and lineups, league tables, fixtures and results, top scorers,<br>
36
+ player profiles and team statistics, head-to-head, transfers, the TV schedule, news stories and videos, in football, with futsal,<br>
37
+ volleyball, basketball and handball leagues and news for other sports. No API key or account is needed.<br>
38
+ It works in Claude, Cursor, Copilot and any other MCP client.
39
+
40
+ [![PyPI](https://img.shields.io/pypi/v/varzesh3-mcp?color=2563eb)](https://pypi.org/project/varzesh3-mcp/)
41
+ [![License: MIT](https://img.shields.io/badge/license-MIT-16a34a)](https://github.com/sepehr071/varzesh3-mcp/blob/main/LICENSE)
42
+
43
+ [For AI agents](#for-ai-agents) · [Quick start](#quick-start) · [What it can do](#what-it-can-do) · [Tools](#tools) · [FAQ](#faq) · [فارسی](#فارسی)
44
+
45
+ </div>
46
+
47
+ ---
48
+
49
+ ## For AI agents
50
+
51
+ - **What:** unofficial MCP server (model context protocol) for varzesh3.com: scores of a day across leagues, one match (events, lineups, referee, stadium, summary video), league tables (also groups and cup brackets), round-by-round fixtures and results, top scorers and other player rankings, team pages (form, squad, transfers), a team's results and next matches, news (latest, most read, by team or league), news story text, videos and search.
52
+ - **Install:** `uvx varzesh3-mcp` or `claude mcp add varzesh3 -- uvx varzesh3-mcp`. Transport: stdio. Needs [uv](https://docs.astral.sh/uv/getting-started/installation/) (Python 3.10+).
53
+ - **Auth:** none, no API key or account. Optional `VARZESH3_MCP_PROXY` (HTTP proxy URL, or a comma-separated list); system proxy settings are ignored.
54
+ - **Access:** read-only. It cannot log in, comment, vote or follow, so no confirmation is needed before calling any tool.
55
+ - **Tools:** 18, all prefixed `v3_`. Typical sequences: `v3_search` (a name) -> `v3_team` / `v3_team_matches` / `v3_news`; `v3_scores` -> `v3_match`; `v3_league` -> `v3_standings` / `v3_top_players`; `v3_head_to_head`; `v3_team_players` -> `v3_player`; `v3_transfers`.
56
+ - **Use when:** the user asks for today's or yesterday's scores, a team's last results or next match, the Iranian Pro League (or any big league) table, top scorers, who plays for a team, a transfer list, or the latest sports news in Persian.
57
+ - **Do not use when:** the user wants per-match possession or shot statistics (Varzesh3 has none; team season averages are in `v3_league_stats`), betting odds, or player career statistics.
58
+ - **Output:** compact JSON. Dates are Persian (Jalali) as the site shows them, times are Tehran time, scores are "home-away". Names and news are Persian.
59
+ - **Machine-readable:** [`server.json`](https://github.com/sepehr071/varzesh3-mcp/blob/main/server.json).
60
+
61
+ ## What it can do
62
+
63
+ - **Scores of a day** (yesterday, today, tomorrow, plus two days either side) for all leagues, football, futsal and NBA, filtered by league, team or live only
64
+ - **Match detail**: goals with scorers and assists, cards, substitutions, lineups by formation line, bench, coaches, referee, stadium and the summary video
65
+ - **League tables** with form, group tables (World Cup, Asian cups) and knockout brackets (Hazfi Cup), for the current or a past season
66
+ - **Fixtures and results** round by round, and a **team's** last results or upcoming matches
67
+ - **Player rankings**: top scorers, assists, clean sheets, yellow and red cards, minutes, hat tricks, average rating
68
+ - **Team page**: recent form, squad by position with numbers and ages, transfers in and out
69
+ - **News, stories and videos**: latest, most read, by team or league, the full story text, goal and summary videos
70
+ - **Search** a Persian name to get the team id the other tools need
71
+ - **Read-only by design**: no login, no posting
72
+
73
+ Example prompts:
74
+
75
+ - "What is the result of Perspolis today?"
76
+ - "Show the Persian Gulf Pro League table."
77
+ - "Top 5 scorers of the Premier League."
78
+ - "Who played for Esteghlal in the last match, and who scored?"
79
+ - <span dir="rtl">جدول لیگ برتر ایران چطوره؟</span>
80
+ - <span dir="rtl">آخرین اخبار استقلال را بگو.</span>
81
+
82
+ ## Quick start
83
+
84
+ You need [uv](https://docs.astral.sh/uv/getting-started/installation/). No API key or account.
85
+
86
+ ```bash
87
+ claude mcp add varzesh3 -- uvx varzesh3-mcp
88
+ ```
89
+
90
+ Claude Desktop, Cursor, Windsurf and Gemini CLI use the same block in their MCP config:
91
+
92
+ ```json
93
+ {
94
+ "mcpServers": {
95
+ "varzesh3": { "command": "uvx", "args": ["varzesh3-mcp"] }
96
+ }
97
+ }
98
+ ```
99
+
100
+ VS Code (`.vscode/mcp.json`): `{"servers": {"varzesh3": {"type": "stdio", "command": "uvx", "args": ["varzesh3-mcp"]}}}`.
101
+ Codex CLI: `codex mcp add varzesh3 -- uvx varzesh3-mcp`. Anything else: `pip install varzesh3-mcp` and run `varzesh3-mcp`.
102
+
103
+ ## Tools
104
+
105
+ Team ids come from `v3_search` (or any table), league ids from `v3_league`, match ids from `v3_scores`, `v3_league_matches` and `v3_team_matches`.
106
+
107
+ | Tool | What it does |
108
+ |---|---|
109
+ | `v3_scores` | Get the live scores, results and fixtures of one day across leagues, as the Varzesh3 live score page lists them |
110
+ | `v3_match` | Get one match: score, status, goals, cards, penalties, substitutions, lineups, referee, stadium, summary video and next matches |
111
+ | `v3_league` | List the football leagues with their ids, or get one league's current season id and past seasons with winners |
112
+ | `v3_standings` | Get the table of a football league (rank, played, won, drawn, lost, goals, points, recent form), group tables or a cup bracket |
113
+ | `v3_league_matches` | Get a football league's matches round by round: scores of played rounds and dates of coming ones |
114
+ | `v3_top_players` | Get the best players of a football league by one statistic, e.g. top scorers or most assists |
115
+ | `v3_team` | Get a football team's page: name, followers, recent form, squad by position and optionally transfers |
116
+ | `v3_team_matches` | Get a football team's latest results or its upcoming matches across all competitions |
117
+ | `v3_news` | Get Varzesh3 news headlines with a short summary: latest, most read, most commented, or about a team, league, player, match or sport |
118
+ | `v3_article` | Read one news story: title, publish time, full text, tags and the match it is about |
119
+ | `v3_videos` | Get Varzesh3 videos (goals, match summaries, interviews): latest, or about one team, league, match or player |
120
+ | `v3_league_stats` | Get a football league's season statistics: goals per match, cards per match, goal timing, streak notes and team rankings |
121
+ | `v3_team_players` | Get the season statistics of one football team's players: goals, assists, appearances, minutes, cards |
122
+ | `v3_player` | Get a player's profile (team, position, shirt number, age, country) with his latest news and videos |
123
+ | `v3_head_to_head` | Get the past meetings of two football teams with a won/drawn/lost summary |
124
+ | `v3_transfers` | Get the football transfer list of a window, club by club: players signed and players who left |
125
+ | `v3_tv_schedule` | Get the live broadcast schedule of sports matches for the next days, with start times and stream links |
126
+ | `v3_search` | Search Varzesh3 for teams, people, leagues, news and videos by name; the way to turn a name into an id |
127
+
128
+ All 18 tools are annotated `readOnlyHint: true`.
129
+
130
+ ## How it works
131
+
132
+ ```text
133
+ AI agent ──MCP over stdio──▶ varzesh3-mcp (your machine) ──HTTPS──▶ web-api.varzesh3.com, search-api.varzesh3.com
134
+ ```
135
+
136
+ The server calls the same public JSON endpoints varzesh3.com's pages use. Requests present a Chrome TLS and header profile
137
+ (through `curl_cffi`), run at most 4 at a time and are cached for 30 seconds. System proxy settings are ignored on purpose;
138
+ set `VARZESH3_MCP_PROXY` if your network needs one.
139
+
140
+ ## FAQ
141
+
142
+ **Does it need an account or key?** No.
143
+
144
+ **Why do I get HTTP 5xx?** Varzesh3's CDN sometimes refuses a network; set `VARZESH3_MCP_PROXY=http://host:port` to route through another exit.
145
+
146
+ **Are there match statistics (possession, shots)?** No, the site does not publish them.
147
+
148
+ **Is it official?** No. It is unaffiliated with Varzesh3, reads only what the public site shows, and is meant for personal and research use. Respect the site's terms.
149
+
150
+ ## فارسی
151
+
152
+ <div dir="rtl">
153
+
154
+ **varzesh3-mcp** یک سرور MCP غیررسمی و فقط‌خواندنی برای ورزش سه (varzesh3.com) است. با آن دستیار هوش مصنوعی می‌تواند نتایج زنده، جزئیات بازی (گل‌ها، کارت‌ها، ترکیب)، جدول لیگ‌ها، برنامه و نتایج، آمار بازیکنان، صفحه تیم‌ها، اخبار و ویدیوها را بخواند. نیازی به کلید API یا حساب کاربری نیست.
155
+
156
+ نصب: `claude mcp add varzesh3 -- uvx varzesh3-mcp`
157
+
158
+ </div>
159
+
160
+ ---
161
+
162
+ Made by Sepehr Radmard (سپهر رادمرد): [github.com/sepehr071](https://github.com/sepehr071) · [linkedin.com/in/sepehr-radmard](https://linkedin.com/in/sepehr-radmard). MIT License.
@@ -0,0 +1,135 @@
1
+ <!-- mcp-name: io.github.sepehr071/varzesh3-mcp -->
2
+
3
+ <div align="center">
4
+
5
+ # varzesh3-mcp: Varzesh3 (ورزش سه) Iranian sports MCP server for AI agents
6
+
7
+ **varzesh3-mcp is an unofficial, read-only MCP server that gives AI agents the data of Varzesh3 (varzesh3.com), the biggest Iranian sports site.**<br>
8
+ Its 18 tools read live scores, match details with goals, cards and lineups, league tables, fixtures and results, top scorers,<br>
9
+ player profiles and team statistics, head-to-head, transfers, the TV schedule, news stories and videos, in football, with futsal,<br>
10
+ volleyball, basketball and handball leagues and news for other sports. No API key or account is needed.<br>
11
+ It works in Claude, Cursor, Copilot and any other MCP client.
12
+
13
+ [![PyPI](https://img.shields.io/pypi/v/varzesh3-mcp?color=2563eb)](https://pypi.org/project/varzesh3-mcp/)
14
+ [![License: MIT](https://img.shields.io/badge/license-MIT-16a34a)](https://github.com/sepehr071/varzesh3-mcp/blob/main/LICENSE)
15
+
16
+ [For AI agents](#for-ai-agents) · [Quick start](#quick-start) · [What it can do](#what-it-can-do) · [Tools](#tools) · [FAQ](#faq) · [فارسی](#فارسی)
17
+
18
+ </div>
19
+
20
+ ---
21
+
22
+ ## For AI agents
23
+
24
+ - **What:** unofficial MCP server (model context protocol) for varzesh3.com: scores of a day across leagues, one match (events, lineups, referee, stadium, summary video), league tables (also groups and cup brackets), round-by-round fixtures and results, top scorers and other player rankings, team pages (form, squad, transfers), a team's results and next matches, news (latest, most read, by team or league), news story text, videos and search.
25
+ - **Install:** `uvx varzesh3-mcp` or `claude mcp add varzesh3 -- uvx varzesh3-mcp`. Transport: stdio. Needs [uv](https://docs.astral.sh/uv/getting-started/installation/) (Python 3.10+).
26
+ - **Auth:** none, no API key or account. Optional `VARZESH3_MCP_PROXY` (HTTP proxy URL, or a comma-separated list); system proxy settings are ignored.
27
+ - **Access:** read-only. It cannot log in, comment, vote or follow, so no confirmation is needed before calling any tool.
28
+ - **Tools:** 18, all prefixed `v3_`. Typical sequences: `v3_search` (a name) -> `v3_team` / `v3_team_matches` / `v3_news`; `v3_scores` -> `v3_match`; `v3_league` -> `v3_standings` / `v3_top_players`; `v3_head_to_head`; `v3_team_players` -> `v3_player`; `v3_transfers`.
29
+ - **Use when:** the user asks for today's or yesterday's scores, a team's last results or next match, the Iranian Pro League (or any big league) table, top scorers, who plays for a team, a transfer list, or the latest sports news in Persian.
30
+ - **Do not use when:** the user wants per-match possession or shot statistics (Varzesh3 has none; team season averages are in `v3_league_stats`), betting odds, or player career statistics.
31
+ - **Output:** compact JSON. Dates are Persian (Jalali) as the site shows them, times are Tehran time, scores are "home-away". Names and news are Persian.
32
+ - **Machine-readable:** [`server.json`](https://github.com/sepehr071/varzesh3-mcp/blob/main/server.json).
33
+
34
+ ## What it can do
35
+
36
+ - **Scores of a day** (yesterday, today, tomorrow, plus two days either side) for all leagues, football, futsal and NBA, filtered by league, team or live only
37
+ - **Match detail**: goals with scorers and assists, cards, substitutions, lineups by formation line, bench, coaches, referee, stadium and the summary video
38
+ - **League tables** with form, group tables (World Cup, Asian cups) and knockout brackets (Hazfi Cup), for the current or a past season
39
+ - **Fixtures and results** round by round, and a **team's** last results or upcoming matches
40
+ - **Player rankings**: top scorers, assists, clean sheets, yellow and red cards, minutes, hat tricks, average rating
41
+ - **Team page**: recent form, squad by position with numbers and ages, transfers in and out
42
+ - **News, stories and videos**: latest, most read, by team or league, the full story text, goal and summary videos
43
+ - **Search** a Persian name to get the team id the other tools need
44
+ - **Read-only by design**: no login, no posting
45
+
46
+ Example prompts:
47
+
48
+ - "What is the result of Perspolis today?"
49
+ - "Show the Persian Gulf Pro League table."
50
+ - "Top 5 scorers of the Premier League."
51
+ - "Who played for Esteghlal in the last match, and who scored?"
52
+ - <span dir="rtl">جدول لیگ برتر ایران چطوره؟</span>
53
+ - <span dir="rtl">آخرین اخبار استقلال را بگو.</span>
54
+
55
+ ## Quick start
56
+
57
+ You need [uv](https://docs.astral.sh/uv/getting-started/installation/). No API key or account.
58
+
59
+ ```bash
60
+ claude mcp add varzesh3 -- uvx varzesh3-mcp
61
+ ```
62
+
63
+ Claude Desktop, Cursor, Windsurf and Gemini CLI use the same block in their MCP config:
64
+
65
+ ```json
66
+ {
67
+ "mcpServers": {
68
+ "varzesh3": { "command": "uvx", "args": ["varzesh3-mcp"] }
69
+ }
70
+ }
71
+ ```
72
+
73
+ VS Code (`.vscode/mcp.json`): `{"servers": {"varzesh3": {"type": "stdio", "command": "uvx", "args": ["varzesh3-mcp"]}}}`.
74
+ Codex CLI: `codex mcp add varzesh3 -- uvx varzesh3-mcp`. Anything else: `pip install varzesh3-mcp` and run `varzesh3-mcp`.
75
+
76
+ ## Tools
77
+
78
+ Team ids come from `v3_search` (or any table), league ids from `v3_league`, match ids from `v3_scores`, `v3_league_matches` and `v3_team_matches`.
79
+
80
+ | Tool | What it does |
81
+ |---|---|
82
+ | `v3_scores` | Get the live scores, results and fixtures of one day across leagues, as the Varzesh3 live score page lists them |
83
+ | `v3_match` | Get one match: score, status, goals, cards, penalties, substitutions, lineups, referee, stadium, summary video and next matches |
84
+ | `v3_league` | List the football leagues with their ids, or get one league's current season id and past seasons with winners |
85
+ | `v3_standings` | Get the table of a football league (rank, played, won, drawn, lost, goals, points, recent form), group tables or a cup bracket |
86
+ | `v3_league_matches` | Get a football league's matches round by round: scores of played rounds and dates of coming ones |
87
+ | `v3_top_players` | Get the best players of a football league by one statistic, e.g. top scorers or most assists |
88
+ | `v3_team` | Get a football team's page: name, followers, recent form, squad by position and optionally transfers |
89
+ | `v3_team_matches` | Get a football team's latest results or its upcoming matches across all competitions |
90
+ | `v3_news` | Get Varzesh3 news headlines with a short summary: latest, most read, most commented, or about a team, league, player, match or sport |
91
+ | `v3_article` | Read one news story: title, publish time, full text, tags and the match it is about |
92
+ | `v3_videos` | Get Varzesh3 videos (goals, match summaries, interviews): latest, or about one team, league, match or player |
93
+ | `v3_league_stats` | Get a football league's season statistics: goals per match, cards per match, goal timing, streak notes and team rankings |
94
+ | `v3_team_players` | Get the season statistics of one football team's players: goals, assists, appearances, minutes, cards |
95
+ | `v3_player` | Get a player's profile (team, position, shirt number, age, country) with his latest news and videos |
96
+ | `v3_head_to_head` | Get the past meetings of two football teams with a won/drawn/lost summary |
97
+ | `v3_transfers` | Get the football transfer list of a window, club by club: players signed and players who left |
98
+ | `v3_tv_schedule` | Get the live broadcast schedule of sports matches for the next days, with start times and stream links |
99
+ | `v3_search` | Search Varzesh3 for teams, people, leagues, news and videos by name; the way to turn a name into an id |
100
+
101
+ All 18 tools are annotated `readOnlyHint: true`.
102
+
103
+ ## How it works
104
+
105
+ ```text
106
+ AI agent ──MCP over stdio──▶ varzesh3-mcp (your machine) ──HTTPS──▶ web-api.varzesh3.com, search-api.varzesh3.com
107
+ ```
108
+
109
+ The server calls the same public JSON endpoints varzesh3.com's pages use. Requests present a Chrome TLS and header profile
110
+ (through `curl_cffi`), run at most 4 at a time and are cached for 30 seconds. System proxy settings are ignored on purpose;
111
+ set `VARZESH3_MCP_PROXY` if your network needs one.
112
+
113
+ ## FAQ
114
+
115
+ **Does it need an account or key?** No.
116
+
117
+ **Why do I get HTTP 5xx?** Varzesh3's CDN sometimes refuses a network; set `VARZESH3_MCP_PROXY=http://host:port` to route through another exit.
118
+
119
+ **Are there match statistics (possession, shots)?** No, the site does not publish them.
120
+
121
+ **Is it official?** No. It is unaffiliated with Varzesh3, reads only what the public site shows, and is meant for personal and research use. Respect the site's terms.
122
+
123
+ ## فارسی
124
+
125
+ <div dir="rtl">
126
+
127
+ **varzesh3-mcp** یک سرور MCP غیررسمی و فقط‌خواندنی برای ورزش سه (varzesh3.com) است. با آن دستیار هوش مصنوعی می‌تواند نتایج زنده، جزئیات بازی (گل‌ها، کارت‌ها، ترکیب)، جدول لیگ‌ها، برنامه و نتایج، آمار بازیکنان، صفحه تیم‌ها، اخبار و ویدیوها را بخواند. نیازی به کلید API یا حساب کاربری نیست.
128
+
129
+ نصب: `claude mcp add varzesh3 -- uvx varzesh3-mcp`
130
+
131
+ </div>
132
+
133
+ ---
134
+
135
+ Made by Sepehr Radmard (سپهر رادمرد): [github.com/sepehr071](https://github.com/sepehr071) · [linkedin.com/in/sepehr-radmard](https://linkedin.com/in/sepehr-radmard). MIT License.
@@ -0,0 +1,55 @@
1
+ [project]
2
+ name = "varzesh3-mcp"
3
+ version = "0.1.0"
4
+ description = "Unofficial read-only MCP server for Varzesh3 (varzesh3.com), the Iranian sports site: live scores, tables, fixtures, teams, top scorers, news."
5
+ readme = "README.md"
6
+ license = "MIT"
7
+ license-files = ["LICENSE"]
8
+ authors = [{ name = "Sepehr Radmard", email = "sepehrr80@gmail.com" }]
9
+ requires-python = ">=3.10"
10
+ keywords = ["mcp", "model-context-protocol", "varzesh3", "varzesh-3", "iran", "football", "livescore", "persian-gulf-pro-league", "standings", "sports", "claude", "persian"]
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/varzesh3-mcp"
31
+ Issues = "https://github.com/sepehr071/varzesh3-mcp/issues"
32
+ Website = "https://mcpfarsi.ir/"
33
+
34
+ [project.scripts]
35
+ varzesh3-mcp = "varzesh3_mcp.server:main"
36
+
37
+ [dependency-groups]
38
+ dev = ["pytest>=8", "ruff>=0.6"]
39
+
40
+ [build-system]
41
+ requires = ["hatchling"]
42
+ build-backend = "hatchling.build"
43
+
44
+ [tool.pytest.ini_options]
45
+ testpaths = ["tests"]
46
+ addopts = "-m 'not live'"
47
+ markers = ["live: calls the real Varzesh3 APIs (run with -m live)"]
48
+
49
+ [tool.ruff]
50
+ line-length = 120
51
+ target-version = "py310"
52
+
53
+ [tool.ruff.lint]
54
+ select = ["E", "F", "I", "B", "UP"]
55
+ 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/varzesh3-mcp",
4
+ "title": "Varzesh3 Sports",
5
+ "description": "Read-only Varzesh3 (varzesh3.com) Iranian sports: live scores, tables, fixtures, teams, news.",
6
+ "repository": {
7
+ "url": "https://github.com/sepehr071/varzesh3-mcp",
8
+ "source": "github"
9
+ },
10
+ "websiteUrl": "https://github.com/sepehr071/varzesh3-mcp",
11
+ "version": "0.1.0",
12
+ "packages": [
13
+ {
14
+ "registryType": "pypi",
15
+ "registryBaseUrl": "https://pypi.org",
16
+ "identifier": "varzesh3-mcp",
17
+ "version": "0.1.0",
18
+ "runtimeHint": "uvx",
19
+ "transport": {
20
+ "type": "stdio"
21
+ },
22
+ "environmentVariables": [
23
+ {
24
+ "name": "VARZESH3_MCP_PROXY",
25
+ "description": "Optional HTTP proxy URL for the Varzesh3 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 Varzesh3 (varzesh3.com), the Iranian sports site: scores, tables, teams, news."""
2
+
3
+ from importlib.metadata import version
4
+
5
+ __version__ = version("varzesh3-mcp")