Skip to main content
Glama
@bearst/lucky-mcp-server

@bearst/lucky-mcp-server

by BearstOzawa

@bearst/lucky-mcp-server

CI npm

中文 | English

Lucky 的 MCP Server。通过 OpenToken 调用 Lucky 3.0 HTTP API,以 stdio 提供反向代理、证书、端口转发、DDNS 及相关模块的工具。

要求

  • Node.js 20 或更高

  • 已启用 OpenToken 的 Lucky 实例(管理端口默认 16601)

认证请求头为 openToken。不使用账号密码,也不维持登录会话。

Related MCP server: mcp-gateway

安装

npx -y @bearst/lucky-mcp-server

MCP 客户端配置:

{
  "mcpServers": {
    "lucky": {
      "command": "npx",
      "args": ["-y", "@bearst/lucky-mcp-server"],
      "env": {
        "LUCKY_BASE_URL": "http://127.0.0.1:16601",
        "LUCKY_OPEN_TOKEN": "<open-token>"
      }
    }
  }
}

从本地构建运行时,将 command 设为 node,args 设为 ["/path/to/lucky-mcp-server/dist/cli.js"]。

环境变量

变量

必填

默认值

说明

LUCKY_BASE_URL

是

—

Lucky 管理端根 URL

LUCKY_OPEN_TOKEN

是

—

OpenToken

LUCKY_TLS_VERIFY

否

true

校验 Lucky HTTPS 证书。自签证书设为 false

LUCKY_TIMEOUT_MS

否

15000

请求超时(毫秒)

LUCKY_DEFAULT_RULE_KEY

否

—

lucky_expose_service 默认使用的 Web 监听 key

LUCKY_DEFAULT_LISTEN_PORT

否

—

lucky_expose_service 默认使用的监听端口

LUCKY_ALLOWED_DOMAIN_SUFFIX

否

—

允许写入的域名后缀,逗号分隔

LUCKY_DEBUG

否

—

向 stderr 输出请求路径,不输出 token

OpenToken 在 Lucky 设置中签发。请遵守 Lucky 对 OpenToken 的使用条款。

工具

列表类工具返回压缩后的字段,不返回 Lucky 原生完整对象。密钥类字段在响应中脱敏。

反向代理

工具

说明

lucky_status

连通性、版本、模块与当前 MCP 配置

lucky_list_web_rules

Web 监听及其子规则(端口、TLS、域名、后端)

lucky_get_web_rule

按 key 读取一条监听

lucky_expose_service

按域名将后端挂到已有监听;已存在则更新后端

lucky_unexpose_service

按域名删除子规则,不删除监听

lucky_set_route_enabled

启用或停用指定域名的子规则

lucky_web_logs

反代访问日志

lucky_expose_service 选择监听的顺序:rule_key → listen_port → LUCKY_DEFAULT_RULE_KEY → LUCKY_DEFAULT_LISTEN_PORT → 已启用的 TLS 监听(优先端口 443)。不会创建新的监听端口。

新增子规则时复制同一监听上已有的反向代理规则,并改写域名与后端。目标监听没有任何反向代理子规则时,提交 PascalCase 最小对象。

证书

工具

说明

lucky_list_certs

证书元数据(不含私钥与 PEM)

lucky_get_cert

按 key 读取证书元数据

lucky_bind_cert

将已有证书绑定到 Web 监听并启用 TLS

lucky_add_custom_cert

上传自定义 PEM

lucky_sync_cert

触发指定证书的 ACME / 手动同步

端口转发

工具

说明

lucky_list_port_forwards

端口转发列表

lucky_upsert_port_forward

按监听端口与协议创建或更新

lucky_delete_port_forward

按 key 删除

lucky_set_port_forward_enabled

启用或停用

lucky_port_forward_logs

日志

DDNS

工具

说明

lucky_list_ddns

任务列表(提供商、域名、最近 IP)

lucky_get_ddns

按 key 读取任务

lucky_set_ddns_enabled

启用或停用

lucky_sync_ddns

立即同步

lucky_ddns_logs

日志

创建新任务需要提供商专用字段,请使用 lucky_api_call。

STUN / WOL / 设置

工具

说明

lucky_list_stun_rules

STUN 规则

lucky_set_stun_enabled

启用或停用 STUN 规则

lucky_stun_logs

STUN 日志

lucky_list_wol_devices

WOL 设备

lucky_wake

按 key、名称或 MAC 发送魔术包

lucky_add_wol_device

添加设备

lucky_get_settings

读取基础设置(密钥脱敏)

计划任务

工具

说明

lucky_list_cron_jobs

任务列表

lucky_upsert_cron_job

按名称(或 key)创建或更新

lucky_delete_cron_job

按 key 删除

lucky_set_cron_enabled

启用或停用

lucky_run_cron_job

立即执行

lucky_cron_logs

日志

FTP / WebDAV

工具

说明

lucky_get_ftp / lucky_get_webdav

配置与运行状态

lucky_update_ftp / lucky_update_webdav

合并写入配置

lucky_ftp_logs / lucky_webdav_logs

日志

Docker

工具

说明

lucky_list_docker

容器、镜像、卷、Compose 项目(只读)

IP 过滤

工具

说明

lucky_list_ip_filters

过滤规则

lucky_get_ip_filter

按 key 读取规则

lucky_list_blocked_ips

端口诱捕已封禁 IP

lucky_unblock_ip

解除封禁

lucky_ip_filter_logs

日志

安全组

工具

说明

lucky_list_security_groups

安全组、授权与用户(只读)

lucky_list_auth_providers

第三方认证配置(只读)

日志、存储、主机

工具

说明

lucky_logs_stats

日志中心统计、位置与数据流

lucky_query_logs

查询日志中心

lucky_list_storage

存储挂载

lucky_set_storage_enabled

启用或停用挂载

lucky_list_local_paths

浏览 Lucky 可见的本地路径

lucky_host_status

主机与模块状态

lucky_list_tunnels

Cloudflared 与 Coraza 实例

lucky_query_ip

IP 库查询

Web 终端

工具

说明

lucky_list_terminal_connections

SSH 连接与会话(不含 SFTP)

lucky_upsert_terminal_connection

按名称创建或更新连接

通用 API

工具

说明

lucky_api_catalog

允许调用的 API 前缀

lucky_api_call

调用前缀白名单内的 Lucky API

lucky_api_call 拒绝以下路径:登录、登出、管理员密码、OpenToken、2FA、配置恢复、进程重启、OAuth 登录、终止主机进程。基础设置仅允许读取。

开发

npm install
npm run typecheck
npm test
npm run lint
npm run build
LUCKY_BASE_URL="http://127.0.0.1:16601" \
LUCKY_OPEN_TOKEN="<open-token>" \
npm run dev

发布

版本记录见 CHANGELOG.md。

创建 GitHub Release 会触发 Publish workflow。仓库 Secrets 需配置 NPM_TOKEN(npm granular token,具备 @bearst/lucky-mcp-server 发布权限)。Release tag 须与 package.json 的 version 一致,例如 v0.1.2。

Publish 只在 Release 或手动 workflow_dispatch 时运行,不会在 push 时发版。

License

MIT

English

MCP server for Lucky. It authenticates with OpenToken and exposes stdio tools for reverse proxy, certificates, port forwarding, DDNS, and related Lucky 3.0 modules.

Requirements

  • Node.js 20+

  • A Lucky instance with OpenToken enabled (admin port defaults to 16601)

The client sends the token in the openToken header. It does not log in with a password or keep a session cookie.

Install

npx -y @bearst/lucky-mcp-server
{
  "mcpServers": {
    "lucky": {
      "command": "npx",
      "args": ["-y", "@bearst/lucky-mcp-server"],
      "env": {
        "LUCKY_BASE_URL": "http://127.0.0.1:16601",
        "LUCKY_OPEN_TOKEN": "<open-token>"
      }
    }
  }
}

To run a local build, set command to node and args to ["/path/to/lucky-mcp-server/dist/cli.js"].

Environment

Variable

Required

Default

Description

LUCKY_BASE_URL

yes

—

Lucky admin base URL

LUCKY_OPEN_TOKEN

yes

—

OpenToken

LUCKY_TLS_VERIFY

no

true

Verify Lucky's TLS certificate. Set false for self-signed certs

LUCKY_TIMEOUT_MS

no

15000

Request timeout in milliseconds

LUCKY_DEFAULT_RULE_KEY

no

—

Default web listener key for lucky_expose_service

LUCKY_DEFAULT_LISTEN_PORT

no

—

Default web listener port for lucky_expose_service

LUCKY_ALLOWED_DOMAIN_SUFFIX

no

—

Comma-separated suffixes allowed for writes

LUCKY_DEBUG

no

—

Log request paths to stderr; tokens are not logged

Issue the token in Lucky settings. Follow Lucky's terms for OpenToken.

Tools

List tools return compact records, not Lucky's full native objects. Secret fields are redacted.

lucky_expose_service selects a listener in this order: rule_key → listen_port → LUCKY_DEFAULT_RULE_KEY → LUCKY_DEFAULT_LISTEN_PORT → an enabled TLS listener (port 443 preferred). It does not create a new listen port. New reverse-proxy routes are cloned from an existing route on the same listener.

lucky_api_call is restricted to allowlisted path prefixes. It rejects login, logout, admin password, OpenToken, 2FA, config restore, process reboot, OAuth login, and host process kill. Base settings are read-only.

See the Chinese section above for the full tool table.

Development

npm install
npm run typecheck
npm test
npm run lint
npm run build

Publish

See CHANGELOG.md. A GitHub Release runs the Publish workflow. Add an NPM_TOKEN repository secret with publish access to @bearst/lucky-mcp-server. The release tag must match package.json version (for example v0.1.2). Publish does not run on push.

License

MIT

Available Tools

61 tools
lucky_add_custom_certAdd a custom PEM certificateA

Upload a custom certificate and private key to Lucky. Prefer lucky_bind_cert for Let's Encrypt certs that already exist in Lucky.

Inputs: name (required), domains (required), key_pem (required), cert_pem (required), +1 more.

lucky_add_wol_deviceAdd a Lucky WOL deviceD
Idempotent

Inputs: mac (required), name (required), broadcast.

lucky_api_callCall an allowlisted Lucky APIA
Destructive

Escape hatch for allowlisted Lucky APIs. Login, admin password, OpenToken, 2FA, restore, reboot, OAuth login, and process kill are blocked. Prefer dedicated tools when one exists.

Inputs: path (required), method (required), body, query.

lucky_api_catalogList allowlisted Lucky API prefixesA
Read-onlyIdempotent

List Lucky API prefixes this MCP is willing to call via lucky_api_call.

Inputs: no named parameters.

lucky_bind_certBind a certificate to a Lucky listenerA
Idempotent

Attach an existing Lucky certificate to a web listener and enable TLS. Select the listener with rule_key, listen_port, or a hostname already on that listener.

Inputs: cert_key (required), domain, rule_key, listen_port.

lucky_cron_logsRead Lucky cron logsD
Read-onlyIdempotent

Inputs: limit.

lucky_ddns_logsRead Lucky DDNS logsD
Read-onlyIdempotent

Inputs: limit.

lucky_delete_cron_jobDelete a Lucky cron jobD
DestructiveIdempotent

Inputs: key (required).

lucky_delete_port_forwardDelete a Lucky port forwardB
DestructiveIdempotent

Delete a port-forward rule by key.

Inputs: key (required).

lucky_expose_serviceExpose a service through LuckyA
Idempotent

Idempotently attach a hostname to an existing Lucky HTTPS/HTTP listener and reverse-proxy it to a backend URL. Reuses the current TLS listener; does not create a new listen port. Domain should be a hostname without http://. Backend should be a full URL such as http://127.0.0.1:3000. If the domain already exists, only the backend (and optional name/auth) is updated.

Inputs: domain (required), backend (required), name, enabled, +6 more.

lucky_ftp_logsRead Lucky FTP logsD
Read-onlyIdempotent

Inputs: limit.

lucky_get_certGet a Lucky certificateA
Read-onlyIdempotent

Get compact certificate metadata by key. Private keys are not returned.

Inputs: key (required).

lucky_get_ddnsGet a Lucky DDNS taskD
Read-onlyIdempotent

Inputs: key (required).

lucky_get_ftpRead Lucky FTP config and statusD
Read-onlyIdempotent

Inputs: no named parameters.

lucky_get_ip_filterGet one Lucky IP filter listD
Read-onlyIdempotent

Inputs: key (required).

lucky_get_settingsRead Lucky base settingsA
Read-onlyIdempotent

Read Lucky base settings. Passwords, OpenToken, and other secrets are redacted. Updating admin account, password, or OpenToken is not available.

Inputs: no named parameters.

lucky_get_webdavRead Lucky WebDAV config and statusD
Read-onlyIdempotent

Inputs: no named parameters.

lucky_get_web_ruleGet one Lucky web ruleB
Read-onlyIdempotent

Get a compact view of one Lucky web listener and its routes by rule key.

Inputs: rule_key (required).

lucky_host_statusLucky host and module statusA
Read-onlyIdempotent

Host overview, connections, processes, module overview, and network interfaces. Process kill is not available.

Inputs: no named parameters.

lucky_ip_filter_logsRead Lucky IP filter / port-trap logsD
Read-onlyIdempotent

Inputs: limit.

lucky_list_auth_providersList Lucky third-party auth providersD
Read-onlyIdempotent

Inputs: no named parameters.

lucky_list_blocked_ipsList Lucky port-trap blocked IPsD
Read-onlyIdempotent

Inputs: no named parameters.

lucky_list_certsList Lucky certificatesA
Read-onlyIdempotent

List SSL certificates in compact form (name, domains, expiry). PEM material is never returned.

Inputs: no named parameters.

lucky_list_cron_jobsList Lucky cron jobsD
Read-onlyIdempotent

Inputs: no named parameters.

lucky_list_ddnsList Lucky DDNS tasksA
Read-onlyIdempotent

List DDNS tasks in compact form (provider, domains, last IP). Provider secrets are redacted. Creating a new provider task is provider-specific; use lucky_api_call only if you already have a native payload.

Inputs: no named parameters.

lucky_list_dockerList Lucky Docker resourcesA
Read-onlyIdempotent

List Docker containers, images, volumes, and compose projects visible to Lucky. Read-only.

Inputs: no named parameters.

lucky_list_ip_filtersList Lucky IP filter rulesD
Read-onlyIdempotent

Inputs: no named parameters.

lucky_list_local_pathsBrowse Lucky local pathsA
Read-onlyIdempotent

List filesystem roots, or files under a path, as Lucky sees them.

Inputs: path.

lucky_list_port_forwardsList Lucky port forwardsA
Read-onlyIdempotent

List port-forward rules in compact form (listen port, target, protocol).

Inputs: no named parameters.

lucky_list_security_groupsList Lucky security groupsA
Read-onlyIdempotent

List security groups, grants, and users. Passwords are redacted. Creating users with passwords is not exposed as a dedicated tool.

Inputs: no named parameters.

lucky_list_storageList Lucky storage mountsD
Read-onlyIdempotent

Inputs: no named parameters.

lucky_list_stun_rulesList Lucky STUN rulesA
Read-onlyIdempotent

List STUN/NAT mapping rules (name, listen port, public address when known).

Inputs: no named parameters.

lucky_list_terminal_connectionsList Lucky web-terminal connections and sessionsA
Read-onlyIdempotent

Passwords and private keys are redacted. SFTP file operations are not exposed.

Inputs: no named parameters.

lucky_list_tunnelsList Lucky tunnels and WAF instancesB
Read-onlyIdempotent

Cloudflared tunnels plus Coraza WAF instances.

Inputs: no named parameters.

lucky_list_web_rulesList Lucky reverse-proxy rulesA
Read-onlyIdempotent

List Lucky web listeners and their reverse-proxy routes in compact form (port, TLS, domains, backends). Use this before exposing a service.

Inputs: no named parameters.

lucky_list_wol_devicesList Lucky WOL devicesD
Read-onlyIdempotent

Inputs: no named parameters.

lucky_logs_statsLucky logs-center stats and locationsD
Read-onlyIdempotent

Inputs: no named parameters.

lucky_port_forward_logsRead Lucky port-forward logsD
Read-onlyIdempotent

Inputs: key (required), limit.

lucky_query_ipQuery Lucky IP databaseD
Read-onlyIdempotent

Inputs: ip (required).

lucky_query_logsQuery Lucky logs-centerC
Read-onlyIdempotent

Query centralized logs. Pass Lucky's native query object; common fields are search, limit, and location.

Inputs: limit, query, search.

lucky_run_cron_jobRun a Lucky cron job nowD

Inputs: key (required).

lucky_set_cron_enabledEnable or disable a Lucky cron jobD
Idempotent

Inputs: key (required), enabled (required).

lucky_set_ddns_enabledEnable or disable a Lucky DDNS taskD
Idempotent

Inputs: key (required), enabled (required).

lucky_set_port_forward_enabledEnable or disable a Lucky port forwardD
Idempotent

Inputs: key (required), enabled (required).

lucky_set_route_enabledEnable or disable a Lucky routeA
Idempotent

Enable or disable the reverse-proxy route for a hostname without deleting it.

Inputs: domain (required), enabled (required).

lucky_set_storage_enabledEnable or disable a Lucky storage mountD
Idempotent

Inputs: key (required), enabled (required).

lucky_set_stun_enabledEnable or disable a Lucky STUN ruleD
Idempotent

Inputs: key (required), enabled (required).

lucky_statusLucky statusA
Read-onlyIdempotent

Probe Lucky connectivity, version, modules, and MCP settings. OpenToken is never returned.

Inputs: no named parameters.

lucky_stun_logsRead Lucky STUN logsD
Read-onlyIdempotent

Inputs: key (required), limit.

lucky_sync_certTrigger Lucky certificate syncA

Trigger ACME/manual sync for an existing certificate key.

Inputs: key (required).

lucky_sync_ddnsTrigger a Lucky DDNS syncC

Force one DDNS task to update now.

Inputs: key (required).

lucky_unblock_ipUnblock an IP from Lucky port-trapD
DestructiveIdempotent

Inputs: ip (required).

lucky_unexpose_serviceRemove a Lucky reverse-proxy hostnameA
DestructiveIdempotent

Remove the reverse-proxy route for a hostname from its Lucky listener. The listener itself is not deleted.

Inputs: domain (required), rule_key.

lucky_update_ftpUpdate Lucky FTP configB
Idempotent

Merge a partial patch into the FTP configure object. Secrets in the response are redacted.

Inputs: patch (required).

lucky_update_webdavUpdate Lucky WebDAV configA
Idempotent

Merge a partial patch into the WebDAV configure object. Secrets in the response are redacted.

Inputs: patch (required).

lucky_upsert_cron_jobCreate or update a Lucky cron jobA
Idempotent

Idempotent by name (or key). expression is a cron spec; command is the shell/http payload Lucky should run.

Inputs: name (required), command (required), expression (required), key, +2 more.

lucky_upsert_port_forwardCreate or update a Lucky port forwardA
Idempotent

Idempotently map an external listen port to an internal ip:port. Matching is by listen_port + protocol unless key is provided. Does not send Lucky's full native object.

Inputs: target_ip (required), listen_port (required), target_port (required), key, +4 more.

lucky_upsert_terminal_connectionCreate or update a Lucky SSH connectionA
Idempotent

Idempotent by name. Stores host/user/port; password is optional and will be redacted in responses.

Inputs: host (required), name (required), key, port, +2 more.

lucky_wakeWake a device through LuckyB

Send a Wake-on-LAN packet. Identify the device by key, name, or MAC.

Inputs: key, mac, name.

lucky_webdav_logsRead Lucky WebDAV logsD
Read-onlyIdempotent

Inputs: limit.

lucky_web_logsRead Lucky reverse-proxy logsB
Read-onlyIdempotent

Read recent access logs for a hostname, a route, or the whole web module. Useful for 502 debugging.

Inputs: limit, domain, rule_key, route_key.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    C2.2/5.0

    Scored across 61 tools

    Disambiguation4/5

    Most tools follow a clear pattern of module plus action (e.g., list_web_rules, upsert_cron_job), making them distinguishable. A few pairs like list_storage vs list_local_paths or logs_stats vs query_logs could be confused, but overall the boundaries are mostly clear.

    Naming Consistency5/5

    All tools share the lucky_ prefix and use lowercase snake_case with consistent action verbs: list, get, upsert, set, delete, run, sync, wake. Minor deviations like cron_logs instead of get_cron_logs do not break the predictable pattern.

    Tool Count1/5

    61 tools is well beyond the 50+ threshold and imposes a huge cognitive load on agents. Even though the tools span multiple modules, the sheer number makes the set feel excessive and hard to navigate.

    Completeness2/5

    The surface is uneven: some modules have full CRUD (cron, port forwards), but many lack common operations such as deleting WoL devices, creating/removing DDNS tasks, deleting certificates, or managing security groups. The generic api_call escape hatch is restricted and cannot fully compensate.

    Maintenance

    ActivityStale
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers

    • F
      license
      Not graded
      quality
      C
      maintenance
      An MCP server with HTTP/stdio support, a web admin panel for managing services, capabilities, and user permissions with Bearer token authentication, enabling relay and access control for MCP tools.
      -
    • A
      license
      Not graded
      quality
      C
      maintenance
      Enables centralized management, proxying, and aggregation of multiple MCP servers behind unified endpoints, with a web GUI, server groups, tool filtering, and lifecycle controls.
      46 npm
      Apache 2.0
    • A
      license
      Not graded
      quality
      B
      maintenance
      Enables managing and observing Technitium DNS Server through MCP, including read-only or read-write tool surfaces, scoped bearer authentication, audit logging, and confirmation gates for destructive operations.
      MIT
    • F
      license
      Not graded
      quality
      C
      maintenance
      Enables users to aggregate, discover, and route remote MCP tools through a unified endpoint, with category-based access tokens, OAuth authorization, and admin management/analytics for self-hosted infrastructure.
      -