myorlen-api 0.1.0__tar.gz

myorlen_api-0.1.0/.claude/settings.local.json

@@ -0,0 +1,13 @@
+{
+  "permissions": {
+    "allow": [
+      "Bash(uv sync:*)",
+      "Bash(uv run:*)",
+      "Bash(python3:*)"
+    ]
+  },
+  "enabledMcpjsonServers": [
+    "pgnig",
+    "myorlen"
+  ]
+}

myorlen_api-0.1.0/.env.example

@@ -0,0 +1,7 @@
+# OrlenID credentials (shared Orlen Group account — takes priority if both pairs are set)
+ORLENID_USERNAME=you@example.com
+ORLENID_PASSWORD=your-orlenid-password
+
+# Native myORLEN eBOK credentials (formerly PGNiG)
+# MYORLEN_USERNAME=you@example.com
+# MYORLEN_PASSWORD=your-myorlen-password

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

@@ -0,0 +1,34 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+
+jobs:
+  test:
+    name: Test (Python ${{ matrix.python-version }})
+    runs-on: ubuntu-latest
+
+    strategy:
+      fail-fast: false
+      matrix:
+        python-version: ["3.12", "3.13"]
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v4
+        with:
+          enable-cache: true
+
+      - name: Install Python ${{ matrix.python-version }}
+        run: uv python install ${{ matrix.python-version }}
+
+      - name: Install dependencies
+        run: uv sync --group dev
+
+      - name: Run tests
+        run: uv run pytest -v

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

@@ -0,0 +1,41 @@
+name: Publish to PyPI
+
+on:
+  release:
+    types: [published]
+  workflow_dispatch:
+
+jobs:
+  publish:
+    name: Build and publish
+    runs-on: ubuntu-latest
+    environment: pypi
+
+    permissions:
+      id-token: write  # required for Trusted Publisher OIDC
+      contents: read
+
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0  # required by hatch-vcs to derive version from git tags
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v4
+        with:
+          enable-cache: true
+
+      - name: Install Python
+        run: uv python install 3.12
+
+      - name: Install dependencies
+        run: uv sync --group dev
+
+      - name: Run tests
+        run: uv run pytest -v
+
+      - name: Build
+        run: uv build
+
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1

myorlen_api-0.1.0/.gitignore

@@ -0,0 +1,23 @@
+# Python-generated files
+__pycache__/
+*.py[oc]
+build/
+dist/
+wheels/
+*.egg-info
+
+# Virtual environments
+.venv
+
+# Secrets
+.env
+
+# HAR capture files (contain session tokens and credentials)
+*.har
+
+# Downloaded invoices
+*.pdf
+
+# Editor swap files
+*.swp
+*.swo

myorlen_api-0.1.0/.mcp.json

@@ -0,0 +1,9 @@
+{
+  "mcpServers": {
+    "myorlen": {
+      "type": "stdio",
+      "command": "uv",
+      "args": ["run", "python", "-m", "myorlen.mcp_server"]
+    }
+  }
+}

myorlen_api-0.1.0/CHANGELOG.md

@@ -0,0 +1,27 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+## [0.1.0] - 2026-03-29
+
+### Added
+- Async client (`MyOrlenClient`) with direct myORLEN eBOK login (`/auth/login`)
+- OrlenID federated login (`use_orlenid=True`) — headless Keycloak form submission via `oid-ws.orlen.pl`
+- Sync wrapper (`MyOrlenClientSync`) with a dedicated event loop for use in non-async contexts
+- Transparent re-login on token expiry (tokens last ~1 hour; up to 2 silent re-login attempts)
+- `get_balance()` — current balance and amount to pay
+- `get_invoices(page, page_size)` — paginated invoice list with gas consumption data (`WearM3`, `WearKWH`)
+- `get_invoice_pdf(invoice_number)` — download invoice PDF as raw bytes
+- Cached account data at login: `user_info`, `agreements`, `metering_points`
+- Typed models: `Address`, `MeteringPoint`, `Agreement`, `UserInfo`, `Balance`, `Invoice`
+- Exception hierarchy: `MyOrlenError`, `MyOrlenAuthError`, `MyOrlenForbiddenError`, `MyOrlenNotFoundError`, `MyOrlenAPIError`
+- MCP server (`myorlen.mcp_server`) exposing four tools: `get_account_info`, `get_balance`, `get_invoices`, `download_invoice`
+- `mcp` optional dependency group: `pip install myorlen-api[mcp]`
+- `myorlen-mcp` script entry point
+- Credential auto-detection: `ORLENID_USERNAME`/`ORLENID_PASSWORD` (OrlenID, preferred) or `MYORLEN_USERNAME`/`MYORLEN_PASSWORD` (native)
+- PEP 561 `py.typed` marker

myorlen_api-0.1.0/CLAUDE.md

@@ -0,0 +1,78 @@
+# myorlen-api
+
+Python client for the myORLEN eBOK self-care portal at `https://ebok.myorlen.pl` (gas accounts, formerly PGNiG).
+
+## Project structure
+
+```
+myorlen/
+├── client.py       # Async MyOrlenClient
+├── sync.py         # MyOrlenClientSync (blocking wrapper)
+├── models.py       # Dataclasses: Address, MeteringPoint, Agreement, UserInfo, Balance, Invoice
+├── exceptions.py   # MyOrlenError hierarchy
+├── _helpers.py     # Response parsers, generate_device_id, token_expires_at
+├── mcp_server.py   # MCP server (requires myorlen-api[mcp])
+└── __init__.py     # Public exports
+scripts/
+└── smoke_test.py   # End-to-end test, reads env vars
+```
+
+## Running
+
+```bash
+uv sync
+MYORLEN_USERNAME=... MYORLEN_PASSWORD=... uv run python scripts/smoke_test.py
+ORLENID_USERNAME=... ORLENID_PASSWORD=... uv run python scripts/smoke_test.py
+```
+
+## Authentication
+
+### Direct login (MYORLEN_USERNAME / MYORLEN_PASSWORD)
+- `POST /auth/login?api-version=3.0` with JSON body containing `identificator`, `accessPin`, `DeviceId`
+- Returns `Token` + `DateExpirationUtc` directly in response body
+- All subsequent requests use `AuthToken: {token}` header (not `Authorization: Bearer`)
+- All requests include `?api-version=3.0`
+- Server returns HTTP 401 + `Code: 1025 "Soft blocked."` for bad credentials
+
+### OrlenID login (ORLENID_USERNAME / ORLENID_PASSWORD)
+Headless OIDC flow — no browser required:
+1. `POST /auth/oid/init-login` → server generates PKCE server-side, returns `RedirectUrl` to Keycloak
+2. `GET RedirectUrl` (oid-ws.orlen.pl) → Keycloak login form; accumulates session cookies
+3. `POST` credentials to form action with `Content-Type: application/x-www-form-urlencoded` → 302 to callback
+4. `GET /auth/oid/after-login-callback?code=...` → server exchanges code, stores token for DeviceId
+5. `GET /auth/get-auth-token?deviceId=...` → returns the token
+
+## Known gotchas
+
+### aiohttp session-level Content-Type override
+The session is created with default `Content-Type: application/json`. For the Keycloak form POST,
+this must be explicitly overridden per-request:
+```python
+session.post(form_action, data={...}, headers={"Content-Type": "application/x-www-form-urlencoded"})
+```
+Without this, aiohttp sends the wrong content type, Keycloak silently re-renders the form (HTTP 200)
+instead of redirecting, and login fails with no obvious error.
+
+### OIDC callback URL contains IdP domain in query parameter
+The successful redirect from Keycloak looks like:
+```
+https://ebok.myorlen.pl/auth/oid/after-login-callback?state=...&iss=https%3A%2F%2Foid-ws.orlen.pl%2F...&code=...
+```
+Checking `"oid-ws.orlen.pl" in location` is a false positive. Use `location.startswith(_BASE_URL)` instead.
+
+### Token expiry
+Tokens expire after ~1 hour (`DateExpirationUtc`). No refresh endpoint exists — re-login on expiry.
+Up to `_MAX_RELOGIN_ATTEMPTS = 2` transparent re-logins before raising `MyOrlenAuthError`.
+
+### MCP server credentials
+Credential env vars (`ORLENID_USERNAME`/`ORLENID_PASSWORD` or `MYORLEN_USERNAME`/`MYORLEN_PASSWORD`)
+are not listed in `.mcp.json` — the subprocess inherits them from the shell environment. This avoids
+Claude Code's "missing environment variables" diagnostic, which fires for any `${VAR}` reference
+whose var is unset. Export the pair you need in `~/.bashrc` / `~/.zshrc` before starting Claude Code.
+
+## Response format
+All API responses wrap data in:
+```json
+{"Code": 0, "Message": null, "TokenExpireDate": "...", ...data fields...}
+```
+`Code != 0` means an error. The `check_response_code()` helper raises `MyOrlenAPIError` for these.

myorlen_api-0.1.0/LICENSE

@@ -0,0 +1,9 @@
+MIT License
+
+Copyright (c) 2026 Pawel Rapkiewicz
+
+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.

myorlen_api-0.1.0/PKG-INFO

@@ -0,0 +1,240 @@
+Metadata-Version: 2.4
+Name: myorlen-api
+Version: 0.1.0
+Summary: Async/sync Python client for the myORLEN eBOK (formerly PGNiG) self-care portal
+Project-URL: Homepage, https://github.com/vincentto13/myorlen-api
+Project-URL: Source, https://github.com/vincentto13/myorlen-api
+Project-URL: Bug Tracker, https://github.com/vincentto13/myorlen-api/issues
+Author-email: Pawel Rapkiewicz <pawel.rapkiewicz@gmail.com>
+License: MIT License
+        
+        Copyright (c) 2026 Pawel Rapkiewicz
+        
+        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.
+License-File: LICENSE
+Keywords: api-client,gas,myorlen,orlen,pgnig,poland,utility
+Classifier: Development Status :: 4 - Beta
+Classifier: Framework :: AsyncIO
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Internet :: WWW/HTTP
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Typing :: Typed
+Requires-Python: >=3.12
+Requires-Dist: aiohttp>=3.9
+Provides-Extra: mcp
+Requires-Dist: mcp>=1.0.0; extra == 'mcp'
+Description-Content-Type: text/markdown
+
+# myorlen-api
+
+Python client library for the [myORLEN eBOK](https://ebok.myorlen.pl) self-care portal (gas accounts, formerly PGNiG).
+Reverse-engineered from browser traffic. Supports both async and sync usage.
+
+## Features
+
+- Direct myORLEN eBOK login and OrlenID federated login (shared Orlen Group account)
+- Automatic re-login on token expiry (tokens last ~1 hour, no refresh endpoint)
+- Fetch account balance
+- List invoices with pagination
+- Download invoice PDFs
+- MCP server for Claude and other AI assistants
+
+## Installation
+
+### From PyPI
+
+```bash
+pip install myorlen-api
+```
+
+### From source (with [uv](https://docs.astral.sh/uv/))
+
+```bash
+git clone https://github.com/vincentto13/myorlen-api.git
+cd myorlen-api
+uv sync
+```
+
+## Configuration
+
+Set credentials for one of the following:
+
+| Env vars | Login mode | Notes |
+|---|---|---|
+| `ORLENID_USERNAME` + `ORLENID_PASSWORD` | OrlenID (`oid-ws.orlen.pl`) | Shared across Orlen Group services. Takes priority if both pairs are set. |
+| `MYORLEN_USERNAME` + `MYORLEN_PASSWORD` | Native myORLEN eBOK | Use if you have a standalone account (formerly PGNiG). |
+
+## Usage
+
+### Async
+
+```python
+from myorlen import MyOrlenClient
+
+# Native myORLEN eBOK credentials
+async with MyOrlenClient("user@example.com", "password") as client:
+    ...
+
+# OrlenID credentials (shared Orlen Group account)
+async with MyOrlenClient("user@example.com", "orlenid-password", use_orlenid=True) as client:
+    print(client.user_info.first_name, client.user_info.last_name)
+
+    for agreement in client.agreements:
+        print(agreement.agreement_number, "active:", agreement.active)
+
+    for mp in client.metering_points:
+        print(mp.ppg_id, mp.tariff, mp.address)
+
+    balance = await client.get_balance()
+    print(balance.value, "PLN  to pay:", balance.amount_to_pay, "PLN")
+
+    invoices = await client.get_invoices(page=1, page_size=12)
+    for inv in invoices:
+        print(inv.invoice_number, inv.issue_date, inv.amount, "PLN  paid:", inv.is_paid)
+
+    # Download a PDF
+    pdf = await client.get_invoice_pdf(invoices[0].invoice_number)
+```
+
+### Sync
+
+```python
+from myorlen import MyOrlenClientSync
+
+with MyOrlenClientSync("user@example.com", "orlenid-password", use_orlenid=True) as client:
+    balance = client.get_balance()
+    invoices = client.get_invoices()
+    pdf = client.get_invoice_pdf(invoices[0].invoice_number)
+```
+
+## Development
+
+### MCP server — local setup with Claude Code
+
+**1. Install the MCP extra**
+
+```bash
+uv sync --extra mcp
+```
+
+**2. Export your credentials**
+
+```bash
+# OrlenID (recommended — works across all Orlen Group services)
+export ORLENID_USERNAME=you@example.com
+export ORLENID_PASSWORD=your-orlenid-password
+
+# — or — native myORLEN eBOK credentials
+export MYORLEN_USERNAME=you@example.com
+export MYORLEN_PASSWORD=your-myorlen-password
+```
+
+Persist in `~/.bashrc` / `~/.zshrc` so they're always available.
+
+**3. Verify the server starts**
+
+```bash
+uv run python -m myorlen.mcp_server
+```
+
+The process should start and wait for MCP input on stdin (no output is normal — that's correct stdio behaviour). Press `Ctrl+C` to stop.
+
+**4. Connect Claude Code**
+
+The repo includes a `.mcp.json` that points Claude Code at the server automatically.
+Open Claude Code from this project directory — it will pick up `.mcp.json` and prompt you to approve the server on first use.
+
+Check the connection inside a Claude Code session:
+
+```
+/mcp
+```
+
+You should see `myorlen` listed as connected with 4 tools.
+
+### Running the smoke test (live API)
+
+```bash
+# OrlenID credentials
+ORLENID_USERNAME=you@example.com ORLENID_PASSWORD=orlenid-secret uv run python scripts/smoke_test.py
+
+# Native myORLEN credentials
+MYORLEN_USERNAME=you@example.com MYORLEN_PASSWORD=myorlen-secret uv run python scripts/smoke_test.py
+```
+
+## MCP Server
+
+The library ships an [MCP](https://modelcontextprotocol.io) server that exposes your myORLEN gas account
+as tools for Claude and other MCP-compatible AI assistants.
+
+### Install
+
+```bash
+pip install myorlen-api[mcp]
+```
+
+### Available tools
+
+| Tool | Description |
+|---|---|
+| `get_account_info` | User profile, agreements and metering points (cached, no network request) |
+| `get_balance` | Current balance and amount to pay |
+| `get_invoices` | Paginated invoice list with gas consumption data |
+| `download_invoice` | Download a PDF invoice — saves to a temp file and returns the path |
+
+### Run standalone
+
+```bash
+# OrlenID credentials
+ORLENID_USERNAME=you@example.com ORLENID_PASSWORD=orlenid-secret uv run python -m myorlen.mcp_server
+
+# Native myORLEN credentials
+MYORLEN_USERNAME=you@example.com MYORLEN_PASSWORD=myorlen-secret uv run python -m myorlen.mcp_server
+```
+
+### Claude Desktop configuration
+
+Add to `~/.config/claude/claude_desktop_config.json`:
+
+```json
+{
+  "mcpServers": {
+    "myorlen": {
+      "command": "uv",
+      "args": ["run", "--project", "/path/to/myorlen-api", "python", "-m", "myorlen.mcp_server"],
+      "env": {
+        "ORLENID_USERNAME": "you@example.com",
+        "ORLENID_PASSWORD": "your-orlenid-password"
+      }
+    }
+  }
+}
+```
+
+Use `ORLENID_USERNAME`/`ORLENID_PASSWORD` for OrlenID, or `MYORLEN_USERNAME`/`MYORLEN_PASSWORD` for native login. If both are set, OrlenID takes priority.
+
+> **Note:** Tokens expire after ~1 hour. The client re-logs in transparently up to 2 times before raising an error — no manual restart needed in most cases.
+
+### Example prompts
+
+Ask Claude naturally:
+
+- *"What's my gas balance?"*
+- *"Show me my last 3 gas invoices"*
+- *"Do I have any unpaid gas bills?"*
+- *"What's my gas consumption for the last invoice?"*
+- *"Download the latest invoice"*
+
+## Acknowledgements
+
+This library was built with the help of [Claude](https://claude.ai) (Anthropic's AI assistant).
+Claude assisted with reverse-engineering the authentication flow from browser HAR captures,
+designing the library architecture, and implementing the async/sync client and MCP server.

myorlen_api-0.1.0/README.md

@@ -0,0 +1,205 @@
+# myorlen-api
+
+Python client library for the [myORLEN eBOK](https://ebok.myorlen.pl) self-care portal (gas accounts, formerly PGNiG).
+Reverse-engineered from browser traffic. Supports both async and sync usage.
+
+## Features
+
+- Direct myORLEN eBOK login and OrlenID federated login (shared Orlen Group account)
+- Automatic re-login on token expiry (tokens last ~1 hour, no refresh endpoint)
+- Fetch account balance
+- List invoices with pagination
+- Download invoice PDFs
+- MCP server for Claude and other AI assistants
+
+## Installation
+
+### From PyPI
+
+```bash
+pip install myorlen-api
+```
+
+### From source (with [uv](https://docs.astral.sh/uv/))
+
+```bash
+git clone https://github.com/vincentto13/myorlen-api.git
+cd myorlen-api
+uv sync
+```
+
+## Configuration
+
+Set credentials for one of the following:
+
+| Env vars | Login mode | Notes |
+|---|---|---|
+| `ORLENID_USERNAME` + `ORLENID_PASSWORD` | OrlenID (`oid-ws.orlen.pl`) | Shared across Orlen Group services. Takes priority if both pairs are set. |
+| `MYORLEN_USERNAME` + `MYORLEN_PASSWORD` | Native myORLEN eBOK | Use if you have a standalone account (formerly PGNiG). |
+
+## Usage
+
+### Async
+
+```python
+from myorlen import MyOrlenClient
+
+# Native myORLEN eBOK credentials
+async with MyOrlenClient("user@example.com", "password") as client:
+    ...
+
+# OrlenID credentials (shared Orlen Group account)
+async with MyOrlenClient("user@example.com", "orlenid-password", use_orlenid=True) as client:
+    print(client.user_info.first_name, client.user_info.last_name)
+
+    for agreement in client.agreements:
+        print(agreement.agreement_number, "active:", agreement.active)
+
+    for mp in client.metering_points:
+        print(mp.ppg_id, mp.tariff, mp.address)
+
+    balance = await client.get_balance()
+    print(balance.value, "PLN  to pay:", balance.amount_to_pay, "PLN")
+
+    invoices = await client.get_invoices(page=1, page_size=12)
+    for inv in invoices:
+        print(inv.invoice_number, inv.issue_date, inv.amount, "PLN  paid:", inv.is_paid)
+
+    # Download a PDF
+    pdf = await client.get_invoice_pdf(invoices[0].invoice_number)
+```
+
+### Sync
+
+```python
+from myorlen import MyOrlenClientSync
+
+with MyOrlenClientSync("user@example.com", "orlenid-password", use_orlenid=True) as client:
+    balance = client.get_balance()
+    invoices = client.get_invoices()
+    pdf = client.get_invoice_pdf(invoices[0].invoice_number)
+```
+
+## Development
+
+### MCP server — local setup with Claude Code
+
+**1. Install the MCP extra**
+
+```bash
+uv sync --extra mcp
+```
+
+**2. Export your credentials**
+
+```bash
+# OrlenID (recommended — works across all Orlen Group services)
+export ORLENID_USERNAME=you@example.com
+export ORLENID_PASSWORD=your-orlenid-password
+
+# — or — native myORLEN eBOK credentials
+export MYORLEN_USERNAME=you@example.com
+export MYORLEN_PASSWORD=your-myorlen-password
+```
+
+Persist in `~/.bashrc` / `~/.zshrc` so they're always available.
+
+**3. Verify the server starts**
+
+```bash
+uv run python -m myorlen.mcp_server
+```
+
+The process should start and wait for MCP input on stdin (no output is normal — that's correct stdio behaviour). Press `Ctrl+C` to stop.
+
+**4. Connect Claude Code**
+
+The repo includes a `.mcp.json` that points Claude Code at the server automatically.
+Open Claude Code from this project directory — it will pick up `.mcp.json` and prompt you to approve the server on first use.
+
+Check the connection inside a Claude Code session:
+
+```
+/mcp
+```
+
+You should see `myorlen` listed as connected with 4 tools.
+
+### Running the smoke test (live API)
+
+```bash
+# OrlenID credentials
+ORLENID_USERNAME=you@example.com ORLENID_PASSWORD=orlenid-secret uv run python scripts/smoke_test.py
+
+# Native myORLEN credentials
+MYORLEN_USERNAME=you@example.com MYORLEN_PASSWORD=myorlen-secret uv run python scripts/smoke_test.py
+```
+
+## MCP Server
+
+The library ships an [MCP](https://modelcontextprotocol.io) server that exposes your myORLEN gas account
+as tools for Claude and other MCP-compatible AI assistants.
+
+### Install
+
+```bash
+pip install myorlen-api[mcp]
+```
+
+### Available tools
+
+| Tool | Description |
+|---|---|
+| `get_account_info` | User profile, agreements and metering points (cached, no network request) |
+| `get_balance` | Current balance and amount to pay |
+| `get_invoices` | Paginated invoice list with gas consumption data |
+| `download_invoice` | Download a PDF invoice — saves to a temp file and returns the path |
+
+### Run standalone
+
+```bash
+# OrlenID credentials
+ORLENID_USERNAME=you@example.com ORLENID_PASSWORD=orlenid-secret uv run python -m myorlen.mcp_server
+
+# Native myORLEN credentials
+MYORLEN_USERNAME=you@example.com MYORLEN_PASSWORD=myorlen-secret uv run python -m myorlen.mcp_server
+```
+
+### Claude Desktop configuration
+
+Add to `~/.config/claude/claude_desktop_config.json`:
+
+```json
+{
+  "mcpServers": {
+    "myorlen": {
+      "command": "uv",
+      "args": ["run", "--project", "/path/to/myorlen-api", "python", "-m", "myorlen.mcp_server"],
+      "env": {
+        "ORLENID_USERNAME": "you@example.com",
+        "ORLENID_PASSWORD": "your-orlenid-password"
+      }
+    }
+  }
+}
+```
+
+Use `ORLENID_USERNAME`/`ORLENID_PASSWORD` for OrlenID, or `MYORLEN_USERNAME`/`MYORLEN_PASSWORD` for native login. If both are set, OrlenID takes priority.
+
+> **Note:** Tokens expire after ~1 hour. The client re-logs in transparently up to 2 times before raising an error — no manual restart needed in most cases.
+
+### Example prompts
+
+Ask Claude naturally:
+
+- *"What's my gas balance?"*
+- *"Show me my last 3 gas invoices"*
+- *"Do I have any unpaid gas bills?"*
+- *"What's my gas consumption for the last invoice?"*
+- *"Download the latest invoice"*
+
+## Acknowledgements
+
+This library was built with the help of [Claude](https://claude.ai) (Anthropic's AI assistant).
+Claude assisted with reverse-engineering the authentication flow from browser HAR captures,
+designing the library architecture, and implementing the async/sync client and MCP server.