lightbill-mcp-server

LightBill MCP Server

mcp-name: io.github.lightnet19/lightbill-mcp-server

MCP (Model Context Protocol) server untuk mengelola LightBill — ISP billing & client management platform — melalui AI agents (Hermes/ARKA, Claude, n8n, dll).

Membungkus 124+ API routes LightBill menjadi 134 tools dengan autentikasi AI API key (X-AI-Key) — tanpa flow login JWT manual.

✨ Fitur

• 👥 Pelanggan — CRUD penuh + isolir/reaktivasi + sesi PPPoE + pemakaian
• 👷 Karyawan — CRUD (owner/admin/noc/kasir/teknisi/reseller)
• 🔧 Router MikroTik — CRUD + sinkronisasi + monitoring (traffic, resource, syslog, ip-pools, ping, top-consumers, active sessions)
• ⚡ OLT & ONT — CRUD + ONT (create/delete/reboot/history) + ZTP + discovery + health
• 💵 Tagihan & Pembayaran — konfirmasi lunas (auto-reaktivasi), generate, verifikasi bukti transfer approve/reject
• 📦 Paket & Template — CRUD paket layanan + template pesan WhatsApp
• 💸 Keuangan — pengeluaran CRUD, laporan daily/monthly/yearly
• 🎫 Hotspot, Mitra, ODC/ODP — batch voucher, deposit reseller, topologi jaringan
• 🎟️ Helpdesk & Chat — tiket (CLAIM/ASSIGN/RESOLVE/CLOSE), live chat
• 📋 Job & Backup — tugas lapangan, export/restore data
• 📊 Analitik & Payroll — churn prediction, forecasting, generate gaji
• 📦 Inventaris — perangkat, bahan habis pakai, movement (borrow/return/install)
• 📡 Radius & Isolir — kick sesi, enforce/reset FUP, lookup
• ⚙️ Pengaturan — payment gateway (Tripay/Duitku/Midtrans/Xendit), profil tenant

🚀 Instalasi

Prasyarat

• LightBill berjalan dengan AI_API_KEY di .env (lihat API-AI-AGENT.md)
• Python 3.10+

Setup

git clone https://github.com/lightnet19/lightbill-mcp-server.git
cd lightbill-mcp-server
python3 -m venv venv
venv/bin/pip install fastmcp httpx
cp run.sh.example run.sh   # lalu isi LIGHTBILL_API_KEY
chmod +x run.sh

Registrasi ke Hermes

hermes mcp add lightbill --command "$(pwd)/run.sh"
# → 134/134 tools enabled

Registrasi ke client MCP lain (Claude Desktop, dll)

{
  "mcpServers": {
    "lightbill": {
      "command": "/path/to/lightbill-mcp-server/run.sh"
    }
  }
}

🔑 Autentikasi

Server membaca LIGHTBILL_API_KEY dari environment (via run.sh). Key dikirim sebagai header X-AI-Key ke setiap request API LightBill.

# run.sh
export LIGHTBILL_BASE_URL="https://your-lightbill-domain.com"
export LIGHTBILL_API_KEY="your-ai-api-key"

🛠️ Daftar Tools (134)

Kategori	Tools
Dashboard	lb_dashboard
Pelanggan	lb_list_customers, lb_customer_create, lb_customer_update, lb_customer_delete, lb_customer_suspend, lb_customer_reactivate, lb_customer_sessions, lb_customer_usage
Karyawan	lb_staff_list, lb_staff_create, lb_staff_update, lb_staff_delete
Router	lb_list_routers, lb_router_create, lb_router_update, lb_router_delete, lb_router_sync, lb_router_test, lb_router_traffic, lb_router_resource, lb_router_syslog, lb_router_ip_pools, lb_router_ping_stats, lb_router_top_consumers, lb_router_active_sessions
OLT	lb_olt_health, lb_olt_create, lb_olt_update, lb_olt_delete, lb_olt_ont_list, lb_olt_ont_create, lb_olt_ont_delete, lb_olt_ont_reboot, lb_olt_ont_history, lb_olt_discovery, lb_olt_test, lb_olt_ztp_list, lb_olt_ztp_create
Tagihan	lb_list_invoices, lb_invoice_mark_paid, lb_invoice_generate
Pembayaran	lb_payment_verification_list, lb_payment_verification_approve, lb_payment_verification_reject, lb_payment_gateway_settings, lb_payment_gateway_set
Paket & Template	lb_list_packages, lb_package_create, lb_package_update, lb_package_delete, lb_list_templates, lb_template_create, lb_template_update, lb_template_delete
Keuangan	lb_finance_monthly, lb_finance_daily, lb_finance_yearly, lb_finance_overview, lb_expense_list, lb_expense_create, lb_expense_update, lb_expense_delete
Hotspot & Mitra	lb_hotspot_list, lb_hotspot_batch_detail, lb_hotspot_create_batch, lb_mitra_list, lb_mitra_create, lb_mitra_deposit, lb_mitra_edit
Network	lb_odc_list, lb_odc_create, lb_odc_update, lb_odc_delete, lb_odp_list, lb_odp_create, lb_odp_update, lb_odp_delete, lb_network_topology
Helpdesk	lb_ticket_list, lb_ticket_create, lb_ticket_action, lb_ticket_message, lb_chat_list, lb_chat_unread, lb_chat_reply, lb_chat_resolve
Job & Backup	lb_job_list, lb_job_create, lb_job_update_status, lb_job_delete, lb_activity_logs, lb_backup_export, lb_backup_logs, lb_backup_restore
Analitik & HR	lb_analytics_churn, lb_analytics_forecasting, lb_analytics_settings, lb_analytics_settings_set, lb_attendance_list, lb_attendance_check_in, lb_hr_incentives, lb_payroll_profiles, lb_payroll_profile_create, lb_payroll_generate, lb_hr_settings
Inventaris	lb_inventory_devices, lb_inventory_device_create, lb_inventory_device_update, lb_inventory_device_delete, lb_inventory_consumables, lb_inventory_consumable_create, lb_inventory_consumable_adjust, lb_inventory_logs, lb_inventory_borrow, lb_inventory_return, lb_inventory_install
Lapangan & Radius	lb_field_registrations, lb_field_registration_approve, lb_field_registration_reject, lb_isolir_lookup, lb_radius_sessions, lb_radius_kick, lb_radius_enforce_fup, lb_radius_reset_fup
WhatsApp	lb_whatsapp_status, lb_whatsapp_start, lb_whatsapp_stop, lb_whatsapp_send
Tenant & Sistem	lb_tenant_update, lb_tenant_subscription, lb_changelog, lb_api_get, lb_api_post

⚠️ Catatan Keamanan

• Aksi destruktif (delete) & berdampak layanan (reboot ONT, kick radius, restore backup) — konfirmasi manusia disarankan.
• Password router/OLT dienkripsi di database LightBill.
• Jangan commit AI_API_KEY ke repo — simpan di run.sh lokal (tidak di-versioned).

📦 Struktur

lightbill-mcp-server/
├── README.md
├── LICENSE
├── pyproject.toml
├── server.json              # MCP Registry manifest
├── run.sh                   # shell wrapper (WAJIB untuk FastMCP + Hermes)
├── run.sh.example           # template wrapper
└── lightbill_mcp_server/
    ├── __init__.py
    ├── __main__.py
    └── server.py            # 134 tools FastMCP

🤝 Kontribusi

Silakan buat issue/PR. Semua endpoint API LightBill baru bisa dibungkus dengan mudah — tambahkan @mcp.tool() di server.py.

📄 Lisensi

MIT — lihat LICENSE.