genieacs-mcp

<p align="center"> <img src="docs/images/banner.svg" alt="GenieACS MCP banner" width="900"/> </p>

<h1 align="center">GenieACS-MCP</h1>

<p align="center"> <a href="https://www.npmjs.com/package/genieacs-mcp"><img src="https://img.shields.io/npm/v/genieacs-mcp?style=flat-square&logo=npm" alt="npm"/></a> <img src="https://img.shields.io/badge/Go-1.24-blue?style=flat-square&logo=go&logoColor=white" alt="Go"/> <a href="https://hub.docker.com/r/drumsergio/genieacs-mcp"><img src="https://img.shields.io/docker/pulls/drumsergio/genieacs-mcp?style=flat-square&logo=docker" alt="Docker Pulls"/></a> <a href="https://github.com/GeiserX/genieacs-mcp/stargazers"><img src="https://img.shields.io/github/stars/GeiserX/genieacs-mcp?style=flat-square&logo=github" alt="GitHub Stars"/></a> <a href="https://github.com/GeiserX/genieacs-mcp/blob/main/LICENSE"><img src="https://img.shields.io/github/license/GeiserX/genieacs-mcp?style=flat-square" alt="License"/></a> <a href="https://glama.ai/mcp/servers/GeiserX/genieacs-mcp"><img src="https://glama.ai/mcp/servers/GeiserX/genieacs-mcp/badge" alt="Glama MCP Server" /></a> </p>

<p align="center"><strong>A tiny bridge that exposes any GenieACS instance as an MCP v1 (JSON-RPC for LLMs) server written in Go.</strong></p>

---

✨ What you get

Type	What for	MCP URI / Tool id
Resources	Consume GenieACS data read-only	genieacs://device/{id}<br>genieacs://file/{name}<br>genieacs://tasks/{id}<br>genieacs://devices/list
Tools	Invoke actions on a CPE through GenieACS	reboot_device<br>download_firmware<br>refresh_parameter

Everything is exposed over a single JSON-RPC endpoint (/mcp).
LLMs / Agents can: initialize → readResource → listTools → callTool … and so on.

---

🚀 Quick-start (Docker Compose)

Follow instructions from https://github.com/GeiserX/genieacs-docker, it is included in the docker compose file there.

📦 Install via npm (stdio transport)

npx genieacs-mcp

Or install globally:

npm install -g genieacs-mcp
genieacs-mcp

This downloads the pre-built Go binary for your platform and runs it with stdio transport, compatible with any MCP client.

🛠 Local build

git clone https://github.com/GeiserX/genieacs-mcp
cd genieacs-mcp

# (optional) create .env from the sample
cp .env.example .env && $EDITOR .env

go run ./cmd/server

🔧 Configuration

Variable	Default	Description
ACS_URL	http://localhost:7557	GenieACS NBI endpoint (without trailing /)
ACS_USER	admin	GenieACS username
ACS_PASS	admin	GenieACS password
TRANSPORT	(empty = HTTP)	Set to stdio for stdio transport

Put them in a .env file (from .env.example) or set them in the environment.

Testing

Tested with Inspector and it is currently fully working. Before making a PR, make sure this MCP server behaves well via this medium.

Lacks Testing with actual MCP clients (client LLMs), so please, submit your PRs to improve descriptions in case it fails to adequately match the services offered by this MCP server.

Example configuration for client LLMs:

{
  "schema_version": "v1",
  "name_for_human": "GenieACS-MCP",
  "name_for_model": "genieacs_mcp",
  "description_for_human": "Read data from GenieACS and run actions on CPEs (reboot, firmware update, parameter refresh).",
  "description_for_model": "Interact with an Auto-Configuration-Server (ACS) that manages routers. First call initialize, then reuse the returned session id in header \"Mcp-Session-Id\" for every other call. Use readResource to fetch URIs that begin with genieacs://. Use listTools to discover available actions and callTool to execute them.",
  "auth": { "type": "none" },
  "api": {
    "type": "jsonrpc-mcp",
    "url":  "http://localhost:8080/mcp",
    "init_method": "initialize",
    "session_header": "Mcp-Session-Id"
  },
  "logo_url": "https://raw.githubusercontent.com/GeiserX/genieacs-docker/master/extra/logo.png",
  "contact_email": "acsdesk@protonmail.com",
  "legal_info_url": "https://github.com/GeiserX/genieacs-mcp/blob/main/LICENSE"
}

Credits

GenieACS – the best open-source ACS

MCP-GO – modern MCP implementation

GoReleaser – painless multi-arch releases

Maintainers

@GeiserX.

Contributing

Feel free to dive in! Open an issue or submit PRs.

GenieACS-MCP follows the Contributor Covenant Code of Conduct.