mcpField
A
albyhub-admin-mcp

albyhub-admin-mcp

Local
github.com/llmops-proFinance0Updated 20w ago
Repository

About albyhub-admin-mcp

albyhub-admin-mcp is an MCP server for agents that need to inspect or administer an Alby Hub Lightning node. It combines typed read tools for node and channel data with a generic HTTP proxy whose writes can be restricted or confirmation-gated.

Key features

  1. 01Read node identity, network, and version
  2. 02View on-chain and Lightning balances
  3. 03List NWC connections and channels
  4. 04Proxy requests to arbitrary API paths
  5. 05Gate writes and log requests

Use cases

  1. 01Check node and channel status
  2. 02Review hub balances and sub-wallets
  3. 03Probe API paths across Hub versions

MCP support

Exposes Alby Hub node information, balances, NWC connections, and channels as tools to MCP clients. A generic proxy supports other API paths, with optional read-only and confirmation controls for writes.

Configuration

Local server config is the same for every client. Copy it into your client’s MCP config file.

mcp.json · Universal config
{
  "mcpServers": {
    "llmops-pro-albyhub-admin": {
      "command": "npx",
      "args": [
        "-y",
        "albyhub-admin-mcp"
      ],
      "env": {
        "ALBYHUB_URL": "<ALBYHUB_URL>",
        "ALBYHUB_TOKEN": "<ALBYHUB_TOKEN>",
        "ALBYHUB_READ_ONLY": "<ALBYHUB_READ_ONLY>"
      }
    }
  }
}
Run commandnpx -y albyhub-admin-mcp
Environment variables to set
ALBYHUB_URLBase URL of the Alby Hub instance
ALBYHUB_TOKENSecretAlby Hub API bearer token
ALBYHUB_READ_ONLYSet true to block all write operations (recommended for first-time setup)

Local servers need a runtime on your machine (e.g. Node.js 18+). Config file locations differ by client; see your client’s docs.

Packages
npmalbyhub-admin-mcp0.1.2

Tools

6

Saved tool list · updated 3w ago

ParameterTypeRequiredDescription
bodyanyNoRequest body — passed as JSON if an object, raw if a string. Ignored for GET/HEAD/OPTIONS.
pathstringYesPath on the Hub, e.g. `/api/info` or `/api/channels`. Combined with ALBYHUB_URL.
queryobjectNoQuery-string params (string → string).
methodenumYesHTTP method. GET/HEAD/OPTIONS are always allowed; others gated by READ_ONLY + REQUIRE_CONFIRM.GET | POST | PUT | PATCH | DELETE | HEAD | OPTIONS
timeout_msintegerNoRequest timeout in ms (default 15000, max 60000).
extra_headersobjectNoExtra HTTP headers to merge in. Useful if your Hub expects `X-API-Key` instead of `Authorization: Bearer`.

Details

From the project README

albyhub-admin-mcp

Node-admin operations on your Alby Hub, exposed to an LLM agent. MCP server that wraps the Alby Hub HTTP API — read node info, balances, channels, NWC sub-wallets. Where NWC (nwc-mcp) ends (it's wallet-scoped), this server picks up: hub-wide on-chain balance, channel state, sub-wallet inventory.

v0.1 — defensive design. Alby Hub's admin API has evolved across versions and isn't publicly versioned in a stable way. So v0.1 ships one generic proxy tool that hits any path (the escape hatch) plus typed wrappers around a few well-established endpoints. If a typed wrapper's endpoint-guess fails against your Hub version, the proxy lets you discover the right path without re-shipping. v0.2 hardens the typed wrappers once smoke-tested against real Hubs.

The six tools

ToolMethodPathPurpose
albyhub_proxy_request**Generic HTTP proxy — escape hatch for any endpoint not yet wrapped.
albyhub_confirm_request**Two-step confirm dispatcher for proxy_request.
albyhub_get_node_infoGET/api/infoNode identity, network, version.
albyhub_get_balancesGET/api/balancesOn-chain + Lightning aggregate balances.
albyhub_list_appsGET/api/appsNWC connections (sub-wallets) provisioned on this hub.
albyhub_list_channelsGET/api/channelsLightning channels with status + capacities.

All typed wrappers are safe GETs. Non-GET behavior runs through albyhub_proxy_request, which is gated by ALBYHUB_READ_ONLY and ALBYHUB_REQUIRE_CONFIRM.

Requirements

  • Node 20+
  • A running Alby Hub instance (desktop app on http://localhost:8080, or self-hosted exposed somewhere)
  • An Alby Hub API token (Settings → Developer / Apps in the Hub UI)

Install

npx -y albyhub-admin-mcp

Configure

cp .env.example .env
# edit .env: set ALBYHUB_URL (default http://localhost:8080) + ALBYHUB_TOKEN
Required
VarPurpose
ALBYHUB_URLBase URL of your Hub. Default http://localhost:8080. Use HTTPS if exposed remotely.
ALBYHUB_TOKENAPI access token. Full-scope tokens can drain the hub's on-chain balance — scope down or use ALBYHUB_READ_ONLY=true if your audience matters.
Optional safety knobs
VarDefaultPurpose
ALBYHUB_READ_ONLYfalseRefuse all non-GET requests via proxy_request. Strongly recommended for first-time setup.
ALBYHUB_REQUIRE_CONFIRMfalseTwo-step confirm for non-GET requests.
ALBYHUB_MAX_REQUESTS_PER_MINUTE30Rolling 60s rate limit.
ALBYHUB_LOG_PATH./albyhub-admin-mcp.logServer log.
ALBYHUB_AUDIT_PATH./albyhub-admin-mcp-audit.logAppend-only JSON-line audit log.

What if my Hub returns 404 on the typed wrappers?

The endpoint path probably differs in your Hub version. Use albyhub_proxy_request to probe — try /api/node, /info, /api/v1/info, etc. Once you find the right path, you can pin it in your usage (and ping the maintainer to fix the typed wrapper in v0.2).

agent: albyhub_proxy_request({ method: "GET", path: "/api/v1/info" })
→ { status: 200, body: { ... } }   // found it

Safety model

The proxy tool's pipeline:

  1. ALBYHUB_READ_ONLY gate — non-GET requests blocked outright.
  2. Rate limit — rolling 60s window on the requests bucket.
  3. ALBYHUB_REQUIRE_CONFIRM gate — non-GET requests return a token; albyhub_confirm_request executes.
  4. HTTP request — Bearer auth, 15s timeout (override via timeout_ms).
  5. Audit log — every attempt (ok / blocked / error) as one structured JSON line.

GET-only convenience wrappers skip steps 1 + 3 (they're safe by construction) but still go through rate limit + audit.

Companion servers

  • nwc-mcp — wallet ops via NIP-47. Use this for per-sub-wallet spend; use albyhub-admin-mcp for hub-wide / node-level operations.
  • nostr-ops-mcp — NOSTR identity + publishing.
  • marketplace-mcp — NIP-15 marketplace storefront.

License

MIT — see LICENSE.

Contact / Issues

Built by LLMOps.Pro.

Comments

Markdown supported

New to MCP?

From what the protocol is to installing your first server, these answers cover most first questions.

An open protocol that defines how AI applications connect to external tools and data in a uniform way. Clients talk to the model; MCP servers provide tools, resources and prompt templates. They exchange standard messages, so one server can be reused by many clients.