Bedolaga MCP Server

MCP-Server zum Abrufen von Benutzerfakten aus Bedolaga Bot per Telegram ID oder interner user_id.

Der Server ist read-only: Über Bedolaga MCP können kein Guthaben geändert, keine Abonnements erstellt oder verlängert, keine Promo-Codes angewendet, keine Rückerstattungen bearbeitet, keine Empfehlungsgelder ausgezahlt und keine anderen Aktionen im Namen des Benutzers ausgeführt werden.

Breaking Migration (1.0.0)

Ab Version 1.0.0 wurde der öffentliche Vertrag der Tools geändert und die alten Namen wurden entfernt. Aktualisieren Sie die Client-Konfiguration:

Außerdem wurde in 1.0.0 der veraltete HTTP-Pfad /mcp entfernt: Sessionful Streamable HTTP wird jetzt am Root-Endpoint / bereitgestellt, wie bei mcp-remnawave. Jede Image-Veröffentlichung erhält drei Tags: :latest, :{version} und :{sha}.

Version 1.0.0 ist der erste Vertrag mit korrekten API-Routen, strukturierten Ergebnissen und einer klaren Verantwortungsgrenze gegenüber Remnawave.

Related MCP server: Monobank MCP Server

Tools

Der Server stellt genau acht Tools bereit, die über das MCP-Protokoll verfügbar sind. Alle Tools sind readonly – Daten werden nicht verändert.

Identitätsvertrag

Jedes Tool akzeptiert genau eines der beiden Felder:

• telegram_id – Ganzzahl, Telegram ID des Benutzers (positiv);

• user_id – Ganzzahl, interne Benutzer-ID in Bedolaga (positiv), wird für E-Mail-only-Tickets des Kundenkontos verwendet.

Wenn kein Feld übergeben wird oder beide übergeben werden, gibt das Tool den Fehler invalid_input zurück. Die Identität wird niemals vom Modell übernommen: supportBot pinnt immer den tatsächlichen Absender – die positive telegram_id aus dem authentifizierten Telegram-Update oder die interne user_id des Kundenkontos für E-Mail-only-Tickets.

bedolaga_user_get

Konto und Guthaben des aktuellen Bedolaga-Benutzers abrufen.

Parameter:

JSON-Antwortfelder (data):

Das Feld promo_group enthält nur name, server_discount_percent, traffic_discount_percent, device_discount_percent.

Interpretationsbeispiel (synthetisch): balance_kopeks: 350000 und balance_rubles: 3500.0 bedeuten ein Guthaben von 3 500 Rubel. has_had_paid_subscription: false bedeutet, dass es noch keine kostenpflichtigen Käufe gab.

bedolaga_billing_get

Mit einem einzigen Aufruf das Guthaben, kürzliche Finanzereignisse und interne Kaufdatensätze von Bedolaga anzeigen – um eine Aufladung von einem Kauf zu unterscheiden.

Parameter:

JSON-Antwortfelder (data):

Jeder Vorgang in transactions:

Jeder Datensatz in bot_subscriptions enthält id, bot_record_status, bot_record_effective_status, is_trial, tariff_id, tariff_name, start_date, end_date, autopay_enabled, autopay_days_before und eine feste note. Der Server bevorzugt die vollständige Upstream-Liste subscriptions, entfernt doppelte Datensätze anhand von id und behält einen Fallback auf das einzelne Legacy-Feld subscription. Das Feld heißt absichtlich bot_record_status: Es ist ein interner Bedolaga-Datensatz und nicht der Status des VPN-Panels. bot_record_effective_status ist ebenfalls ein bot-seitiger effektiver Status (vom Bot aus status und end_date berechnet), nicht der Zustand des Panels.

Interpretationsbeispiel (synthetisch): latest_completed_deposit: {amount_kopeks: 350000} und purchased_after_latest_deposit: false – das Geld wurde dem Guthaben gutgeschrieben, aber ein separater Kauf nach der Aufladung wurde nicht abgeschlossen.

bedolaga_referrals_get

Empfehlungsübersicht des aktuellen Benutzers abrufen.

Parameter:

JSON-Antwortfelder (data):

Zurückgegeben wird die Statistik nur des Kontoinhabers. Telegram-ID, interne IDs, Benutzername, Namen, Guthaben und Aktivität eingeladener Benutzer werden niemals zurückgegeben.

bedolaga_subscription_get

Bot-seitige Abonnementdatensätze und Lebenszyklusdaten abrufen (created_at, start_date, end_date, is_trial, autopay_enabled).

Parameter: telegram_id oder user_id (genau eines).

Gibt has_subscription_records, active_record_count, eine Liste subscriptions und festes meta zurück. Das Feld bot_record_status ist ein interner Bot-Datensatz und nicht der Status des VPN-Panels (der tatsächliche Zustand wird über Remnawave MCP geprüft).

bedolaga_tickets_get

Eine Übersicht der eigenen Support-Tickets abrufen (id, title, status, priority, Erstellungs-/Aktualisierungs-/Schließungsdaten) ohne Nachrichtentexte und Medien.

Parameter: telegram_id oder user_id (genau eines), limit (Standard 10, maximal 50).

bedolaga_payment_status_get

Den Verlauf der Finanztransaktionen und den Abschlussstatus im Abrechnungssystem des Bots abrufen (completed / not_completed / unknown).

Parameter: telegram_id oder user_id (genau eines), limit (Standard 5, maximal 20).

Der Status not_completed bedeutet lediglich, dass die Transaktion im Bot-Billing nicht abgeschlossen ist, und nicht einen Fehler oder ein Warten seitens des Zahlungsgateways.

bedolaga_promocode_check

Die globale Definition des Promocodes, Gültigkeitsdauer, Aktivität, Bonus und verbleibende Verwendungen prüfen.

Parameter: code (erforderlich), telegram_id oder user_id (genau eines zur Identitätszuordnung).

Gibt den maskierten Code (code_masked), das Kennzeichen globally_valid, reason_code (not_found, inactive, not_yet_valid, expired_or_exhausted, lookup_incomplete) und user_eligibility: "unknown" zurück.

bedolaga_gifts_get

Den Verlauf der Geschenkkäufe des Kontoinhabers abrufen.

Parameter: telegram_id oder user_id (genau eines), limit (Standard 20, maximal 50).

Zeigt nur den Kaufvorgang von Geschenken (Buchhaltung); Geschenk-Tokens, Empfänger und Aktivierungsstatus werden nicht offengelegt.

Entscheidungstabelle

Wie das LLM (supportBot) die Bedolaga- und Remnawave-Daten je Szenario verwenden soll:

Ergebnisformat

Jedes Tool gibt JSON im Text-MCP-Content mit einer einheitlichen Hülle zurück:

• Erfolg: ok: true, source: "bedolaga-mcp", tool, data, meta;

• Fehler: ok: false, source, tool, error.code, sichere error.message, error.retryable.

Der rohe Antworttext der Bedolaga-API und Python-Ausnahmen des Modells werden nicht zurückgegeben. Die Tools geben keine E-Mail, keinen Abo-Link, keinen Crypto-Link, keine Schlüssel, keine externen Zahlungs-IDs, keine Receipt-IDs, keine Remnawave-IDs und keine personenbezogenen Daten von Empfohlenen zurück.

Fehlercodes

Die Benutzermeldung wird nur aus der sicheren error.message erstellt und offenbart niemals den HTTP-Body oder eine interne URL.

Transporte

Der Server unterstützt zwei Transporte auf derselben Server-Factory und derselben Tool-Registry:

Der Endpunkt / ist der einzige, bedient aber zwei Protokoll-Ären gleichzeitig; das SDK v2 erkennt selbst, zu welcher Ära jede Anfrage gehört, anhand des Headers MCP-Protocol-Version:

• Modernes Protokoll 2026-07-28 — zustandslos/sitzungslos. Jeder POST auf / ist eigenständig: Der Server gibt niemals Mcp-Session-Id aus und speichert keinen Zustand zwischen Anfragen. Offizielle MCP-SDK-v2-Clients (siehe „Offizieller SDK-v2-Client“ unten) verwenden diesen Modus automatisch.

• Legacy-Clients mit Initialize-Handshake (Protokolle bis einschließlich 2025-11-25, einschließlich 2024-11-05) erhalten den Header Mcp-Session-Id als Antwort auf initialize und müssen ihn in allen nachfolgenden Anfragen übermitteln. DELETE / mit diesem Header beendet genau diese Sitzung; andere Sitzungen und moderne Clients sind davon nicht betroffen.

GET /health liefert die Prozess-Liveness und die Serverversion, ohne Konfiguration und Geheimnisse preiszugeben.

Versionskompatibilität

Der Tool-Vertrag wurde gegen den genannten Upstream-Commit und die Referenz mcp-remnawave v3.2.1 geprüft.

Anforderungen

• Python 3.11+

• Docker (optional)

• Bereitgestellter Bedolaga Bot mit Web-API

• API-Schlüssel von Bedolaga (wird im Admin-Panel des Bots ausgegeben)

Schnellstart

1. Klonen

git clone https://github.com/mitetenov/bedolaga-mcp.git
cd bedolaga-mcp

2. Konfigurieren

cp .env.example .env
# Заполнить BEDOLAGA_API_URL и BEDOLAGA_API_KEY

3. Starten

Streamable HTTP (empfohlen):

# Установить зависимости
pip install -r requirements.txt

# Запустить HTTP-сервер
BEDOLAGA_API_URL=https://your-bot.example.com \
BEDOLAGA_API_KEY=your-key \
python3 http_server.py

Der Server lauscht auf http://0.0.0.0:3100, der MCP-Endpunkt ist die Wurzel /.

Stdio:

BEDOLAGA_API_URL=https://your-bot.example.com \
BEDOLAGA_API_KEY=your-key \
python3 bedolaga_server.py

Über Docker:

docker compose up -d

Das Docker-Image startet standardmäßig einen Streamable-HTTP-Server auf Port 3100.

Verbindung als MCP-Server

Streamable HTTP

Der Server ist per HTTP auf Port 3100 erreichbar, der Endpunkt ist die Wurzel / (http://localhost:3100).

Hermes Agent

# ~/.hermes/config.yaml
mcp_servers:
  bedolaga:
    transport: streamable-http
    url: "http://localhost:3100"
    env:
      BEDOLAGA_API_URL: "https://your-bot.example.com"
      BEDOLAGA_API_KEY: "your-api-key"

Claude Desktop

{
  "mcpServers": {
    "bedolaga": {
      "type": "streamableHttp",
      "url": "http://localhost:3100"
    }
  }
}

Cursor / VS Code

{
  "mcpServers": {
    "bedolaga": {
      "transport": "streamable-http",
      "url": "http://localhost:3100"
    }
  }
}

Prüfung über curl (Legacy-Kompatibilitätsprüfung)

Rohes JSON-RPC über curl verwendet Legacy-Initialize-Handshake (Protokoll 2024-11-05) — das ist eine manuelle Abwärtskompatibilitätsprüfung und nicht die Art, wie moderne Clients kommunizieren. Moderne MCP-SDK-v2-Clients handeln das Protokoll 2026-07-28 automatisch aus und erhalten keine Mcp-Session-Id (siehe „Offizieller SDK-v2-Client (modernes Protokoll)“ unten).

# Liveness
curl -s http://localhost:3100/health

# Legacy initialize handshake (получить session ID; работает для протоколов вплоть до 2025-11-25)
curl -s -X POST http://localhost:3100/ \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -d '{"jsonrpc":"2.0","method":"initialize","params":{"protocolVersion":"2024-11-05","capabilities":{}},"id":1}' \
  -D - | grep -i mcp-session-id

# Список инструментов (с session ID)
curl -s -X POST http://localhost:3100/ \
  -H "Content-Type: application/json" \
  -H "Mcp-Session-Id: <SESSION_ID>" \
  -d '{"jsonrpc":"2.0","method":"tools/list","id":2}'

# Вызов инструментов
# Пользователь и баланс
curl -s -X POST http://localhost:3100/ \
  -H "Content-Type: application/json" \
  -H "Mcp-Session-Id: <SESSION_ID>" \
  -d '{"jsonrpc":"2.0","method":"tools/call","params":{"name":"bedolaga_user_get","arguments":{"telegram_id":123456789}},"id":3}'

# Биллинг (операции и внутренние записи покупок)
curl -s -X POST http://localhost:3100/ \
  -H "Content-Type: application/json" \
  -H "Mcp-Session-Id: <SESSION_ID>" \
  -d '{"jsonrpc":"2.0","method":"tools/call","params":{"name":"bedolaga_billing_get","arguments":{"telegram_id":123456789,"limit":20}},"id":4}'

# Реферальная сводка
curl -s -X POST http://localhost:3100/ \
  -H "Content-Type: application/json" \
  -H "Mcp-Session-Id: <SESSION_ID>" \
  -d '{"jsonrpc":"2.0","method":"tools/call","params":{"name":"bedolaga_referrals_get","arguments":{"telegram_id":123456789}},"id":5}'

# Завершение legacy-сессии (для современного протокола 2026-07-28 не требуется и не применяется)
curl -s -X DELETE http://localhost:3100/ \
  -H "Mcp-Session-Id: <SESSION_ID>"

Offizieller SDK-v2-Client (modernes Protokoll)

Der offizielle Client aus dem Python MCP SDK v2 (mcp==2.0.0) handelt das Protokoll selbst aus — 2026-07-28, wenn der Server es unterstützt, andernfalls Legacy-Handshake — ohne manuelles Erstellen von _meta oder Headern:

import asyncio

from mcp.client.client import Client


async def main() -> None:
    async with Client("http://localhost:3100/", mode="auto") as client:
        print("negotiated protocol:", client.protocol_version)  # "2026-07-28" against this server

        tools = await client.list_tools()
        print([tool.name for tool in tools.tools])

        result = await client.call_tool(
            "bedolaga_user_get", {"telegram_id": 123456789}
        )
        print(result.content)


asyncio.run(main())

mode="auto" – dieselbe Aushandlung, die supportBot verwendet: Der Client entscheidet selbst, ob ein moderner Server oder ein Legacy-Server vorliegt, und der aufrufende Code muss die Protokoll-Ära nicht im Voraus kennen.

Stdio-Transport

Hermes Agent

# ~/.hermes/config.yaml
mcp_servers:
  bedolaga:
    command: "python3"
    args: ["/path/to/bedolaga-mcp/bedolaga_server.py"]
    env:
      BEDOLAGA_API_URL: "https://your-bot.example.com"
      BEDOLAGA_API_KEY: "your-api-key"

Claude Desktop

{
  "mcpServers": {
    "bedolaga": {
      "command": "python3",
      "args": ["/path/to/bedolaga-mcp/bedolaga_server.py"],
      "env": {
        "BEDOLAGA_API_URL": "https://your-bot.example.com",
        "BEDOLAGA_API_KEY": "your-api-key"
      }
    }
  }
}

Cursor / VS Code

In .cursor/mcp.json oder settings.json einfügen:

{
  "mcpServers": {
    "bedolaga": {
      "command": "python3",
      "args": ["/path/to/bedolaga-mcp/bedolaga_server.py"],
      "env": {
        "BEDOLAGA_API_URL": "https://your-bot.example.com",
        "BEDOLAGA_API_KEY": "your-api-key"
      }
    }
  }
}

Sitzungsverwaltung

Der Streamable-HTTP-Transport ist dual-era, und Sitzungen gelten nur für eine der beiden Epochen:

• Legacy initialize-handshake (Protokolle bis einschließlich 2025-11-25): Nach initialize gibt der Server den Header Mcp-Session-Id zurück, den der Client in allen nachfolgenden Anfragen übermitteln muss. DELETE / mit diesem Header beendet nur die angegebene Sitzung; ein Client kann keine fremde Sitzung beenden oder wiederverwenden.

• Modernes Protokoll 2026-07-28: stateless/sessionless – der Server gibt niemals Mcp-Session-Id aus, und DELETE / ist für solche Clients nicht erforderlich und wird nicht angewendet.

Umgebungsvariablen

Aus Kompatibilitätsgründen werden die Legacy-Variablen HOST/PORT akzeptiert, wenn MCP_HTTP_HOST/MCP_HTTP_PORT nicht gesetzt sind.

Upstream API

Bedolaga Web API: X-API-Key im Header. Verwendete Routen:

• GET /users/by-telegram-id/{telegram_id} — Benutzer anhand der Telegram-ID;

• GET /users/{user_id} — Benutzer anhand der internen ID (E-Mail-only-Tickets);

• GET /transactions?user_id=... — Transaktionen mit Filtern und Paginierung;

• GET /partners/referrers/{user_id} — Referral-Karte.

Weitere Informationen: https://docs.bedolagam.ru

Einschränkungen der ersten Version

• Keine provider-spezifischen Zahlungsversuche. Bedolaga gibt nur Transaktionen zurück, die zu Einträgen in der gemeinsamen Tabelle transactions geworden sind. Rohe Versuche des Zahlungsanbieters, die nicht zu einem Eintrag geworden sind, sind nicht verfügbar.

• Kein Lesen des Redis-Warenkorbs des Benutzers. Die aktuelle Web API bietet dafür keinen sicheren Read-only-Endpunkt. Das aktuelle Problem „eingezahlt, aber kein Kauf“ wird zuverlässig anhand der Differenz zwischen deposit und subscription_payment diagnostiziert (siehe decision table).

• E-Mail-only-Lookup wird unterstützt. Für Tickets des Kontos ohne Telegram-ID akzeptiert der Server die interne user_id (positive Ganzzahl) und löst sie über GET /users/{user_id} auf. supportBot pinnt die interne user_id des Kontos (Absolutwert des negativen synthetischen Conversation-Keys) – für solche Tickets sind Bedolaga-Daten verfügbar, während Remnawave-Tools identity_unavailable zurückgeben, weil ein solcher Benutzer keine Telegram-Identität und keinen nachgewiesenen Eintrag im Panel hat.

Rollback

Wenn BEDOLAGA_MCP_ENABLED=false in supportBot gesetzt wird, kehrt es in den Remnawave-only-Modus zurück: Bedolaga MCP wird nicht verbunden, seine Tools verschwinden aus der Allowlist, und die Webhook-/Poller-Verarbeitung von Tickets (BEDOLAGA_ENABLED) bleibt unabhängig. Der Rollback berührt weder die Benutzerbasis noch die Finanzdaten – Bedolaga MCP ist read-only und speichert keinen Zustand.

Auch das Zurücksetzen des Images bedolaga-mcp auf den Tag 1.1.0 (letztes Release vor der Migration auf MCP SDK v2, nur Legacy-Ära von Streamable HTTP) ist sicher: Der supportBot-Client auf MCP SDK v2 wechselt automatisch (Auto-Fallback) auf den Legacy-Initialize-Handshake, wenn der Server nicht auf das moderne Protokoll 2026-07-28 antwortet. Daher bleiben die Bedolaga-MCP-Tools ohne zusätzliche Konfiguration verfügbar.