@bearst/lucky-mcp-server
Provides read-only visibility into Cloudflared tunnel instances managed by a Lucky instance.
Provides read-only tools for listing Docker containers, images, volumes, and Compose projects via a Lucky instance.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@@bearst/lucky-mcp-server List all reverse proxy rules and check the server status"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
@bearst/lucky-mcp-server
中文 | 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-serverMCP 客户端配置:
{
"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 管理端根 URL |
| 是 | — | OpenToken |
| 否 |
| 校验 Lucky HTTPS 证书。自签证书设为 |
| 否 |
| 请求超时(毫秒) |
| 否 | — |
|
| 否 | — |
|
| 否 | — | 允许写入的域名后缀,逗号分隔 |
| 否 | — | 向 stderr 输出请求路径,不输出 token |
OpenToken 在 Lucky 设置中签发。请遵守 Lucky 对 OpenToken 的使用条款。
工具
列表类工具返回压缩后的字段,不返回 Lucky 原生完整对象。密钥类字段在响应中脱敏。
反向代理
工具 | 说明 |
| 连通性、版本、模块与当前 MCP 配置 |
| Web 监听及其子规则(端口、TLS、域名、后端) |
| 按 key 读取一条监听 |
| 按域名将后端挂到已有监听;已存在则更新后端 |
| 按域名删除子规则,不删除监听 |
| 启用或停用指定域名的子规则 |
| 反代访问日志 |
lucky_expose_service 选择监听的顺序:rule_key → listen_port → LUCKY_DEFAULT_RULE_KEY → LUCKY_DEFAULT_LISTEN_PORT → 已启用的 TLS 监听(优先端口 443)。不会创建新的监听端口。
新增子规则时复制同一监听上已有的反向代理规则,并改写域名与后端。目标监听没有任何反向代理子规则时,提交 PascalCase 最小对象。
证书
工具 | 说明 |
| 证书元数据(不含私钥与 PEM) |
| 按 key 读取证书元数据 |
| 将已有证书绑定到 Web 监听并启用 TLS |
| 上传自定义 PEM |
| 触发指定证书的 ACME / 手动同步 |
端口转发
工具 | 说明 |
| 端口转发列表 |
| 按监听端口与协议创建或更新 |
| 按 key 删除 |
| 启用或停用 |
| 日志 |
DDNS
工具 | 说明 |
| 任务列表(提供商、域名、最近 IP) |
| 按 key 读取任务 |
| 启用或停用 |
| 立即同步 |
| 日志 |
创建新任务需要提供商专用字段,请使用 lucky_api_call。
STUN / WOL / 设置
工具 | 说明 |
| STUN 规则 |
| 启用或停用 STUN 规则 |
| STUN 日志 |
| WOL 设备 |
| 按 key、名称或 MAC 发送魔术包 |
| 添加设备 |
| 读取基础设置(密钥脱敏) |
计划任务
工具 | 说明 |
| 任务列表 |
| 按名称(或 key)创建或更新 |
| 按 key 删除 |
| 启用或停用 |
| 立即执行 |
| 日志 |
FTP / WebDAV
工具 | 说明 |
| 配置与运行状态 |
| 合并写入配置 |
| 日志 |
Docker
工具 | 说明 |
| 容器、镜像、卷、Compose 项目(只读) |
IP 过滤
工具 | 说明 |
| 过滤规则 |
| 按 key 读取规则 |
| 端口诱捕已封禁 IP |
| 解除封禁 |
| 日志 |
安全组
工具 | 说明 |
| 安全组、授权与用户(只读) |
| 第三方认证配置(只读) |
日志、存储、主机
工具 | 说明 |
| 日志中心统计、位置与数据流 |
| 查询日志中心 |
| 存储挂载 |
| 启用或停用挂载 |
| 浏览 Lucky 可见的本地路径 |
| 主机与模块状态 |
| Cloudflared 与 Coraza 实例 |
| IP 库查询 |
Web 终端
工具 | 说明 |
| SSH 连接与会话(不含 SFTP) |
| 按名称创建或更新连接 |
通用 API
工具 | 说明 |
| 允许调用的 API 前缀 |
| 调用前缀白名单内的 Lucky API |
lucky_api_call 拒绝以下路径:登录、登出、管理员密码、OpenToken、2FA、配置恢复、进程重启、OAuth 登录、终止主机进程。基础设置仅允许读取。
开发
npm install
npm run typecheck
npm test
npm run lint
npm run buildLUCKY_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 |
| yes | — | Lucky admin base URL |
| yes | — | OpenToken |
| no |
| Verify Lucky's TLS certificate. Set |
| no |
| Request timeout in milliseconds |
| no | — | Default web listener key for |
| no | — | Default web listener port for |
| no | — | Comma-separated suffixes allowed for writes |
| 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 buildPublish
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 toolslucky_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 deviceDIdempotent
Inputs: mac (required), name (required), broadcast.
lucky_api_callCall an allowlisted Lucky APIADestructive
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 prefixesARead-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 listenerAIdempotent
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 logsDRead-onlyIdempotent
Inputs: limit.
lucky_ddns_logsRead Lucky DDNS logsDRead-onlyIdempotent
Inputs: limit.
lucky_delete_cron_jobDelete a Lucky cron jobDDestructiveIdempotent
Inputs: key (required).
lucky_delete_port_forwardDelete a Lucky port forwardBDestructiveIdempotent
Delete a port-forward rule by key.
Inputs: key (required).
lucky_expose_serviceExpose a service through LuckyAIdempotent
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 logsDRead-onlyIdempotent
Inputs: limit.
lucky_get_certGet a Lucky certificateARead-onlyIdempotent
Get compact certificate metadata by key. Private keys are not returned.
Inputs: key (required).
lucky_get_ddnsGet a Lucky DDNS taskDRead-onlyIdempotent
Inputs: key (required).
lucky_get_ftpRead Lucky FTP config and statusDRead-onlyIdempotent
Inputs: no named parameters.
lucky_get_ip_filterGet one Lucky IP filter listDRead-onlyIdempotent
Inputs: key (required).
lucky_get_settingsRead Lucky base settingsARead-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 statusDRead-onlyIdempotent
Inputs: no named parameters.
lucky_get_web_ruleGet one Lucky web ruleBRead-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 statusARead-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 logsDRead-onlyIdempotent
Inputs: limit.
lucky_list_auth_providersList Lucky third-party auth providersDRead-onlyIdempotent
Inputs: no named parameters.
lucky_list_blocked_ipsList Lucky port-trap blocked IPsDRead-onlyIdempotent
Inputs: no named parameters.
lucky_list_certsList Lucky certificatesARead-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 jobsDRead-onlyIdempotent
Inputs: no named parameters.
lucky_list_ddnsList Lucky DDNS tasksARead-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 resourcesARead-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 rulesDRead-onlyIdempotent
Inputs: no named parameters.
lucky_list_local_pathsBrowse Lucky local pathsARead-onlyIdempotent
List filesystem roots, or files under a path, as Lucky sees them.
Inputs: path.
lucky_list_port_forwardsList Lucky port forwardsARead-onlyIdempotent
List port-forward rules in compact form (listen port, target, protocol).
Inputs: no named parameters.
lucky_list_security_groupsList Lucky security groupsARead-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 mountsDRead-onlyIdempotent
Inputs: no named parameters.
lucky_list_stun_rulesList Lucky STUN rulesARead-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 sessionsARead-onlyIdempotent
Passwords and private keys are redacted. SFTP file operations are not exposed.
Inputs: no named parameters.
lucky_list_tunnelsList Lucky tunnels and WAF instancesBRead-onlyIdempotent
Cloudflared tunnels plus Coraza WAF instances.
Inputs: no named parameters.
lucky_list_web_rulesList Lucky reverse-proxy rulesARead-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 devicesDRead-onlyIdempotent
Inputs: no named parameters.
lucky_logs_statsLucky logs-center stats and locationsDRead-onlyIdempotent
Inputs: no named parameters.
lucky_port_forward_logsRead Lucky port-forward logsDRead-onlyIdempotent
Inputs: key (required), limit.
lucky_query_ipQuery Lucky IP databaseDRead-onlyIdempotent
Inputs: ip (required).
lucky_query_logsQuery Lucky logs-centerCRead-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 jobDIdempotent
Inputs: key (required), enabled (required).
lucky_set_ddns_enabledEnable or disable a Lucky DDNS taskDIdempotent
Inputs: key (required), enabled (required).
lucky_set_port_forward_enabledEnable or disable a Lucky port forwardDIdempotent
Inputs: key (required), enabled (required).
lucky_set_route_enabledEnable or disable a Lucky routeAIdempotent
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 mountDIdempotent
Inputs: key (required), enabled (required).
lucky_set_stun_enabledEnable or disable a Lucky STUN ruleDIdempotent
Inputs: key (required), enabled (required).
lucky_statusLucky statusARead-onlyIdempotent
Probe Lucky connectivity, version, modules, and MCP settings. OpenToken is never returned.
Inputs: no named parameters.
lucky_stun_logsRead Lucky STUN logsDRead-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-trapDDestructiveIdempotent
Inputs: ip (required).
lucky_unexpose_serviceRemove a Lucky reverse-proxy hostnameADestructiveIdempotent
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 configBIdempotent
Merge a partial patch into the FTP configure object. Secrets in the response are redacted.
Inputs: patch (required).
lucky_update_webdavUpdate Lucky WebDAV configAIdempotent
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 jobAIdempotent
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 forwardAIdempotent
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 connectionAIdempotent
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 logsDRead-onlyIdempotent
Inputs: limit.
lucky_web_logsRead Lucky reverse-proxy logsBRead-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
Scored across 61 tools
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.
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.
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.
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
Related MCP Connectors
Managed MCP gateway with OAuth, per-agent permissions, shared accounts and activity logs.
Secure and manage MCP servers through the Speakeasy AI Control Plane from your agent.
Governed MCP gateway: one endpoint for your tools, with credential custody and audit log.
MCP gateway and cloud hosting for MCP servers, agents and apps like RAG, managed from your agent.
Related MCP Servers
- FlicenseNot gradedqualityCmaintenanceAn 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.-
- AlicenseNot gradedqualityCmaintenanceEnables centralized management, proxying, and aggregation of multiple MCP servers behind unified endpoints, with a web GUI, server groups, tool filtering, and lifecycle controls.46 npmApache 2.0
- AlicenseNot gradedqualityBmaintenanceEnables 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
- FlicenseNot gradedqualityCmaintenanceEnables 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.-