Kontomanager

Un servidor no oficial para gestionar cuentas móviles austriacas de marcas como yesss!, Georg y XOXO.

GitHub
2

Documentación

Servidor MCP para Kontomanager

Un servidor MCP no oficial para las marcas móviles austriacas yesss!, Georg y XOXO.

Este servidor actúa como un puente, exponiendo las funcionalidades de la interfaz web de Kontomanager a través de un conjunto estructurado de herramientas MCP. Permite leer información de la cuenta de forma programática, consultar el consumo, descargar facturas y modificar ajustes como el desvío de llamadas.

✨ Características

Este servidor está diseñado con un enfoque primero las herramientas para una amplia compatibilidad con clientes. Proporciona un conjunto completo de funciones que reflejan el portal web:

  • Leer datos de la cuenta: Obtener consumo, saldo, detalles del plan, números de teléfono e historial de llamadas.
  • Gestionar facturas: Listar facturas anteriores y descargar su contenido en PDF.
  • Modificar ajustes: Cambiar ajustes de la SIM como roaming y configurar reglas detalladas de desvío de llamadas.
  • Flujos de trabajo de alto nivel: Usar herramientas simples para acciones comunes como desactivar el buzón de voz.

🛠️ Herramientas disponibles

El servidor expone toda la funcionalidad a través de herramientas, que pueden ser llamadas por un cliente MCP o un LLM.

Herramientas de recuperación de datos

  • get_account_usage(): Recupera la vista general principal de la cuenta, incluidos los detalles del plan, las estadísticas de consumo y el saldo de crédito.
  • get_phone_numbers(): Lista todos los números de teléfono asociados con la cuenta conectada.
  • list_bills(): Obtiene una lista de facturas disponibles (solo metadatos).
  • download_bill(bill_number, document_type): Obtiene una factura específica o su registro detallado (EGN) y devuelve su contenido binario (PDF).
  • get_call_history(): Recupera una lista de llamadas recientes y mensajes SMS.
  • get_sim_settings(): Lee el estado actual de todos los ajustes relacionados con la SIM (por ejemplo, estado de roaming, bloqueo de datos).
  • get_call_forwarding_settings(): Lee los ajustes actuales de desvío de llamadas y buzón de voz.

Herramientas de acción y flujo de trabajo

  • switch_active_phone_number(subscriber_id): Cambia el número de teléfono activo para la sesión.
  • toggle_roaming(enabled): Una herramienta simple para activar o desactivar el roaming internacional.
  • set_sim_setting(setting_name, enabled): Una herramienta de bajo nivel para activar o desactivar un ajuste específico de la SIM.
  • set_call_forwarding_rule(...): Una herramienta de bajo nivel para configurar una regla específica de desvío de llamadas (por ejemplo, desviar cuando está ocupado a un número específico).

🗣️ Ejemplo de uso

Puedes interactuar con este servidor usando lenguaje natural en un cliente MCP compatible. El LLM del cliente seleccionará y ejecutará las herramientas apropiadas.

  • "¿Cuál es mi consumo de datos y saldo actual?"
    • → Llama a get_account_usage()
  • "Muéstrame mis últimas facturas."
    • → Llama a list_bills()
  • "Descarga mi factura número 8177 y el registro detallado correspondiente."
    • → Llama a download_bill(bill_number='8177', document_type='bill')
    • → Llama a download_bill(bill_number='8177', document_type='egn')
  • "Activa el roaming para mi viaje."
    • → Llama a toggle_roaming(enabled=True)
  • "Desvía todas mis llamadas al +436811234567 cuando mi línea esté ocupada."
    • → Llama a set_call_forwarding_rule(condition='wtel', target='a', target_number='+436811234567')

⚙️ Configuración

El servidor requiere tus credenciales de Kontomanager. Estas deben proporcionarse mediante variables de entorno, que configurarás en el archivo de configuración de tu cliente MCP.

Las variables requeridas son:

  • KONTOMANAGER_BRAND: La marca de tu operador móvil. Valores admitidos: "yesss", "georg", "xoxo".
  • KONTOMANAGER_USERNAME: Tu número de teléfono de inicio de sesión o nombre de usuario.
  • KONTOMANAGER_PASSWORD: La contraseña de tu cuenta de Kontomanager.

🚀 Configuración y uso

Este proyecto es un servidor MCP y está diseñado para ser lanzado y gestionado por un cliente MCP. No lo ejecutas de forma independiente.

  1. Clona el repositorio:

    git clone https://github.com/dhofer/mcp-server-kontomanager.git

  2. Configura tu cliente MCP: Añade una nueva definición de servidor al archivo de configuración de tu cliente MCP. El comando usará uv run para ejecutar el servidor desde su directorio local. Asegúrate de usar la ruta absoluta al repositorio clonado.

    {
  "mcpServers": {
    "kontomanager": {
      "command": "uv",
      "args": [
        "run",
        "--directory",
        "/absolute/path/to/mcp-server-kontomanager",
        "python",
        "src/server.py"
      ],
      "env": {
        "KONTOMANAGER_BRAND": "yesss",
        "KONTOMANAGER_USERNAME": "43681...",
        "KONTOMANAGER_PASSWORD": "your_secret_password"
      }
    }
  }
}

⚠️ Advertencias importantes: Léelas antes de usar

Privacidad de datos

Cuando usas este servidor MCP, cualquier dato recuperado por las herramientas (como el consumo de tu cuenta, números de teléfono o detalles de facturas) se envía al Modelo de Lenguaje Grande (LLM) que impulsa tu cliente MCP. Esto significa que una empresa de terceros (por ejemplo, OpenAI, Google, Anthropic) procesará esta información potencialmente sensible. Ten en cuenta las implicaciones de privacidad y revisa las políticas de tu proveedor de LLM antes de usar este servidor.

Riesgo financiero

Este servidor proporciona herramientas que pueden cambiar la configuración de tu cuenta móvil en tiempo real. Acciones como toggle_roaming o set_call_forwarding_rule pueden generar cargos significativos y reales en tu factura telefónica, especialmente si se configuran incorrectamente. Eres el único responsable de todos y cada uno de los costos incurridos como resultado del uso de estas herramientas. Úsalas con extrema precaución.

🧑‍💻 Filosofía de desarrollo

Este proyecto es, para todos los efectos, codificado por vibración. Fue construido basándose en la intuición y las necesidades específicas del desarrollador. Aunque busca ser funcional, puede no seguir las prácticas de ingeniería más estrictas y tiene pruebas limitadas. ¡Se animan encarecidamente las solicitudes de extracción para mejorar la robustez, añadir pruebas o refinar el código!

Descargo de responsabilidad: Este es un proyecto no oficial y no está afiliado, respaldado ni apoyado por A1 Telekom Austria AG ni por ninguna de sus marcas. La estructura del sitio web de Kontomanager puede cambiar en cualquier momento, lo que podría romper la funcionalidad de este servidor. Úsalo bajo tu propio riesgo.