milligold-mcp 0.1.0__tar.gz

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

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

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

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

milligold_mcp-0.1.0/.github/dependabot.yml

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

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

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

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

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

milligold_mcp-0.1.0/.gitignore

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

milligold_mcp-0.1.0/LICENSE

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

milligold_mcp-0.1.0/PKG-INFO

@@ -0,0 +1,76 @@
+Metadata-Version: 2.5
+Name: milligold-mcp
+Version: 0.1.0
+Summary: Unofficial read-only MCP server for Milli.gold (milli.gold): live 18k gold price, price history, platform stats.
+Project-URL: Homepage, https://github.com/sepehr071/milligold-mcp
+Project-URL: Issues, https://github.com/sepehr071/milligold-mcp/issues
+Author-email: Sepehr Radmard <sepehrr80@gmail.com>
+License-Expression: MIT
+License-File: LICENSE
+Keywords: gold,iran,mcp,milli-gold,model-context-protocol,prices
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Requires-Python: >=3.10
+Requires-Dist: curl-cffi>=0.16.3
+Requires-Dist: httpx-curl-cffi>=0.1.5
+Requires-Dist: httpx>=0.27
+Requires-Dist: mcp<3,>=2.2
+Description-Content-Type: text/markdown
+
+<!-- mcp-name: io.github.sepehr071/milligold-mcp -->
+
+<div align="center">
+
+<img src="https://raw.githubusercontent.com/sepehr071/milligold-mcp/main/.github/banner.png" alt="milligold-mcp: unofficial Milli.gold MCP server for Claude, Cursor and Copilot" width="100%">
+
+</div>
+
+# milligold-mcp: Milli.gold price MCP server for AI agents
+
+An unofficial, read-only MCP server for [Milli.gold](https://milli.gold) (میلی), an Iranian online platform for buying and
+selling 18k melted gold by the milligram: the live gold price, price history and platform statistics.
+
+## For AI agents
+
+- **What:** unofficial MCP server for the public price and statistics endpoints of milli.gold.
+- **Install:** `uvx milligold-mcp` or `claude mcp add milligold -- uvx milligold-mcp`. Transport: stdio. Needs [uv](https://docs.astral.sh/uv/getting-started/installation/) (Python 3.10+).
+- **Auth:** none. Optional `MILLIGOLD_MCP_PROXY` (HTTP proxy URL, or a comma-separated list); system proxy settings are ignored.
+- **Access:** read-only, so no confirmation is needed before calling any tool. It cannot log in, trade or read a wallet.
+- **Tools:** 3, all prefixed `mg_`. Typical sequence: `mg_get_price` -> `mg_price_history`.
+- **Output:** compact JSON. Prices are quoted by the site in **Rial per milligram** of 18k gold; replies also carry Rial and Toman per gram.
+- **Machine-readable:** [`server.json`](server.json).
+
+## Tools
+
+| Tool | Purpose |
+|---|---|
+| `mg_get_price` | Current Milli.gold price of 18k melted gold: Rial per milligram, Rial per gram, Toman per gram |
+| `mg_price_history` | Price series for a day, week or month (thinned to at most 50 points) with first, last, high, low and change % |
+| `mg_platform_stats` | Headline numbers: users, trade count, gold traded and held (kg), burned gold, branches |
+
+## Units
+
+`price18` is Rial per **milligram** (1 gram = 1000 mg): 268,900 Rial/mg = 268,900,000 Rial/g = 26,890,000 Toman/g, which
+matches "price of 1 gram of 18k gold" on the site. Times are Tehran time (UTC+3:30). The price is Milli.gold's own, with no tax or
+making charge, so it differs slightly from market quotes elsewhere.
+
+Only three public read endpoints exist (`milli-price/external`, `milli-price/widget/external`, `milli-overall-report`); everything else on the site needs a login.
+
+## Development
+
+```bash
+uv sync
+uv run ruff check . && uv run ruff format --check .
+uv run python -m pytest -q          # offline unit tests
+uv run python -m pytest -m live -q  # calls milli.gold
+uv build
+```
+
+Not affiliated with Milli.gold. Prices are informational, not financial advice. MIT license.

milligold_mcp-0.1.0/README.md

@@ -0,0 +1,50 @@
+<!-- mcp-name: io.github.sepehr071/milligold-mcp -->
+
+<div align="center">
+
+<img src="https://raw.githubusercontent.com/sepehr071/milligold-mcp/main/.github/banner.png" alt="milligold-mcp: unofficial Milli.gold MCP server for Claude, Cursor and Copilot" width="100%">
+
+</div>
+
+# milligold-mcp: Milli.gold price MCP server for AI agents
+
+An unofficial, read-only MCP server for [Milli.gold](https://milli.gold) (میلی), an Iranian online platform for buying and
+selling 18k melted gold by the milligram: the live gold price, price history and platform statistics.
+
+## For AI agents
+
+- **What:** unofficial MCP server for the public price and statistics endpoints of milli.gold.
+- **Install:** `uvx milligold-mcp` or `claude mcp add milligold -- uvx milligold-mcp`. Transport: stdio. Needs [uv](https://docs.astral.sh/uv/getting-started/installation/) (Python 3.10+).
+- **Auth:** none. Optional `MILLIGOLD_MCP_PROXY` (HTTP proxy URL, or a comma-separated list); system proxy settings are ignored.
+- **Access:** read-only, so no confirmation is needed before calling any tool. It cannot log in, trade or read a wallet.
+- **Tools:** 3, all prefixed `mg_`. Typical sequence: `mg_get_price` -> `mg_price_history`.
+- **Output:** compact JSON. Prices are quoted by the site in **Rial per milligram** of 18k gold; replies also carry Rial and Toman per gram.
+- **Machine-readable:** [`server.json`](server.json).
+
+## Tools
+
+| Tool | Purpose |
+|---|---|
+| `mg_get_price` | Current Milli.gold price of 18k melted gold: Rial per milligram, Rial per gram, Toman per gram |
+| `mg_price_history` | Price series for a day, week or month (thinned to at most 50 points) with first, last, high, low and change % |
+| `mg_platform_stats` | Headline numbers: users, trade count, gold traded and held (kg), burned gold, branches |
+
+## Units
+
+`price18` is Rial per **milligram** (1 gram = 1000 mg): 268,900 Rial/mg = 268,900,000 Rial/g = 26,890,000 Toman/g, which
+matches "price of 1 gram of 18k gold" on the site. Times are Tehran time (UTC+3:30). The price is Milli.gold's own, with no tax or
+making charge, so it differs slightly from market quotes elsewhere.
+
+Only three public read endpoints exist (`milli-price/external`, `milli-price/widget/external`, `milli-overall-report`); everything else on the site needs a login.
+
+## Development
+
+```bash
+uv sync
+uv run ruff check . && uv run ruff format --check .
+uv run python -m pytest -q          # offline unit tests
+uv run python -m pytest -m live -q  # calls milli.gold
+uv build
+```
+
+Not affiliated with Milli.gold. Prices are informational, not financial advice. MIT license.

milligold_mcp-0.1.0/pyproject.toml

@@ -0,0 +1,54 @@
+[project]
+name = "milligold-mcp"
+version = "0.1.0"
+description = "Unofficial read-only MCP server for Milli.gold (milli.gold): live 18k gold price, price history, platform stats."
+readme = "README.md"
+license = "MIT"
+license-files = ["LICENSE"]
+authors = [{ name = "Sepehr Radmard", email = "sepehrr80@gmail.com" }]
+requires-python = ">=3.10"
+keywords = ["mcp", "model-context-protocol", "milli-gold", "iran", "gold", "prices"]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Intended Audience :: Developers",
+    "Operating System :: OS Independent",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Topic :: Scientific/Engineering :: Artificial Intelligence",
+]
+dependencies = [
+    "mcp>=2.2,<3",
+    "httpx>=0.27",
+    "httpx-curl-cffi>=0.1.5",
+    "curl-cffi>=0.16.3",
+]
+
+[project.urls]
+Homepage = "https://github.com/sepehr071/milligold-mcp"
+Issues = "https://github.com/sepehr071/milligold-mcp/issues"
+
+[project.scripts]
+milligold-mcp = "milligold_mcp.server:main"
+
+[dependency-groups]
+dev = ["pytest>=8", "ruff>=0.6"]
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+addopts = "-m 'not live'"
+markers = ["live: calls the real Milli.gold API (run with -m live)"]
+
+[tool.ruff]
+line-length = 120
+target-version = "py310"
+
+[tool.ruff.lint]
+select = ["E", "F", "I", "B", "UP"]
+ignore = ["E501"]  # long Field(description=...) strings read better on one line

milligold_mcp-0.1.0/server.json

@@ -0,0 +1,32 @@
+{
+  "$schema": "https://static.modelcontextprotocol.io/schemas/2025-12-11/server.schema.json",
+  "name": "io.github.sepehr071/milligold-mcp",
+  "title": "Milli.gold Prices",
+  "description": "Unofficial read-only Milli.gold: live 18k gold price per milligram, history and platform stats.",
+  "repository": {
+    "url": "https://github.com/sepehr071/milligold-mcp",
+    "source": "github"
+  },
+  "websiteUrl": "https://github.com/sepehr071/milligold-mcp",
+  "version": "0.1.0",
+  "packages": [
+    {
+      "registryType": "pypi",
+      "registryBaseUrl": "https://pypi.org",
+      "identifier": "milligold-mcp",
+      "version": "0.1.0",
+      "runtimeHint": "uvx",
+      "transport": {
+        "type": "stdio"
+      },
+      "environmentVariables": [
+        {
+          "name": "MILLIGOLD_MCP_PROXY",
+          "description": "Optional HTTP proxy URL for milli.gold 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.",
+          "isRequired": false,
+          "isSecret": false
+        }
+      ]
+    }
+  ]
+}

milligold_mcp-0.1.0/src/milligold_mcp/__init__.py

@@ -0,0 +1,5 @@
+"""Unofficial MCP server for Milli.gold (milli.gold)."""
+
+from importlib.metadata import version
+
+__version__ = version("milligold-mcp")

milligold_mcp-0.1.0/src/milligold_mcp/gold.py

@@ -0,0 +1,110 @@
+"""Milli.gold tools: live 18k gold price, price history, platform statistics."""
+
+from __future__ import annotations
+
+from datetime import datetime, timedelta, timezone
+from typing import Annotated, Any, Literal
+
+from pydantic import Field
+
+from .http import API, ApiError, fetch
+from .registry import tool
+
+TEHRAN = timezone(timedelta(hours=3, minutes=30))  # no DST since 2022
+
+
+def _data(body: Any, what: str) -> dict[str, Any]:
+    data = body.get("data") if isinstance(body, dict) else None
+    if not isinstance(body, dict) or body.get("code") != 0 or not isinstance(data, dict):
+        raise ApiError(f"Milli.gold returned no {what}.")
+    return data
+
+
+def _price(rial_per_mg: int) -> dict[str, Any]:
+    return {
+        "rial_per_mg": rial_per_mg,
+        "rial_per_gram": rial_per_mg * 1000,
+        "toman_per_gram": rial_per_mg * 100,
+    }
+
+
+@tool("Milli.gold live gold price")
+async def mg_get_price() -> dict[str, Any]:
+    """Get the current Milli.gold price of 18k melted gold, in Rial per milligram and per gram.
+
+    Milli.gold sells gold by the milligram (1 gram = 1000 mg); the quote is the platform's own price
+    with no tax or making charge. `as_of` is Tehran time. For the trend over a day, week or month use
+    mg_price_history.
+    """
+    d = _data(await fetch(f"{API}/milli-price/external"), "price")
+    if not isinstance(d.get("price18"), int | float):
+        raise ApiError("Milli.gold returned no price.")
+    return {"as_of": d.get("date"), **_price(d["price18"]), "karat": 18}
+
+
+@tool("Milli.gold price history")
+async def mg_price_history(
+    period: Annotated[
+        Literal["DAILY", "WEEKLY", "MONTHLY"],
+        Field(description="Window: DAILY = last ~24 h (15-min points), WEEKLY = last week, MONTHLY = last ~month."),
+    ] = "DAILY",
+    points: Annotated[int, Field(description="Max points to return, evenly spaced (2-50).", ge=2, le=50)] = 24,
+) -> dict[str, Any]:
+    """Get the Milli.gold 18k gold price series for a day, week or month, with high, low and change.
+
+    Prices are Rial per milligram; `time` is Tehran time. Points are thinned evenly to `points`.
+    """
+    prices = _data(await fetch(f"{API}/milli-price/widget/external"), "price history").get("prices")
+    series = prices.get(period) if isinstance(prices, dict) else None
+    if not series or not all(isinstance(p, dict) and p.get("timestamp") and p.get("value") for p in series):
+        raise ApiError(f"Milli.gold returned no {period} history.")
+    series = sorted(series, key=lambda p: p["timestamp"])
+    # Like the site: stats span every series from this window's start (the day's peak counts in the week) plus the live price.
+    every = [
+        p
+        for v in prices.values()
+        if isinstance(v, list)
+        for p in v
+        if isinstance(p, dict) and p.get("value") and p.get("timestamp", 0) >= series[0]["timestamp"]
+    ]
+    values = [p["value"] for p in sorted(every, key=lambda p: p["timestamp"])]
+    try:
+        values.append(_data(await fetch(f"{API}/milli-price/external"), "price")["price18"])
+    except (ApiError, KeyError):
+        pass  # live price is a refinement; the series alone is still valid
+    step = (len(series) - 1) / (points - 1)
+    picked = [series[round(i * step)] for i in range(min(points, len(series)))] if len(series) > points else series
+    first, last = values[0], values[-1]
+    return {
+        "period": period,
+        "unit": "rial_per_mg",
+        "first": first,
+        "last": last,
+        "high": max(values),
+        "low": min(values),
+        "change_percent": round((last - first) / first * 100, 2),
+        "points": [
+            {
+                "time": datetime.fromtimestamp(p["timestamp"] / 1000, TEHRAN).strftime("%Y-%m-%d %H:%M"),
+                "price": p["value"],
+            }
+            for p in picked
+        ],
+    }
+
+
+@tool("Milli.gold platform statistics")
+async def mg_platform_stats() -> dict[str, Any]:
+    """Get Milli.gold's headline numbers: users, trades, gold traded, gold held and branches.
+
+    Figures are rounded totals the company publishes; weights are in kilograms. For prices use mg_get_price.
+    """
+    d = _data(await fetch(f"{API}/milli-overall-report"), "statistics")
+    return {
+        "users": d.get("overallNumberOfUsers"),
+        "trade_transactions": d.get("overallNumberOfTradeTransactions"),
+        "traded_gold_kg": d.get("overallTradedMilliTurnoverInKg"),
+        "user_balances_kg": d.get("overallUsersMilliBalanceInKg"),
+        "burned_kg": d.get("overallBurnedMilliAmountInKg"),
+        "branches_and_representatives": d.get("numberOfBranchesAndRepresentatives"),
+    }