Skill: kci-lnk/fn-knock-mcp (version 1.0.1)

--- name: fn-knock-mcp description: Manage fn-knock gateway via its admin API — reverse proxy, DDNS, SSL/ACME, tunnels (FRP/Cloudflared), scanner, whitelist, and more. Requires fn-knock running on localhost:7998. metadata: {"openclaw":{"emoji":"🌐","requires":{"anyBins":["python3"]},"os":["linux"]}} --- ## What is fn-knock? fn-knock is a self-hosted gateway/reverse proxy solution for NAS and home lab environments. This MCP Server exposes its admin API (100+ endpoints) as structured tools for AI assistants. ## Installation ### 1. Install the MCP package ```bash pip install mcp requests # or with uv uv tool install fn-knock-mcp # (if published to PyPI) ``` If installing from source: ```bash cd fn_knock_mcp pip install -e . ``` ### 2. Configure HMAC Secret (3 ways, pick one) fn-knock's admin API requires HMAC authentication. The MCP auto-resolves the secret using this priority: **方式 A — 环境变量（推荐）** ```bash export FN_KNOCK_HMAC_SECRET="your-secret-here" ``` **方式 B — 凭证文件** ```bash mkdir -p ~/.config/fn-knock echo "HMAC_SECRET=your-secret-here" > ~/.config/fn-knock/credentials chmod 600 ~/.config/fn-knock/credentials ``` **方式 C — 自动检测（仅限本地运行 fn-knock）** 如果 fn-knock 正在本机运行（http://localhost:7998），MCP 会自动从页面 HTML 中提取密钥，无需额外配置。 ### 3. Add to OpenClaw MCP Settings Edit your `~/.openclaw/openclaw.json` (or use the OpenClaw web UI): ```json { "mcpServers": { "fn-knock": { "command": "python", "args": ["-m", "fn_knock_mcp.server"], "env": { "FN_KNOCK_BASE_URL": "http://localhost:7998/api/admin" } } } } ``` Or reference the provided `mcp.json`: ```json { "mcpServers": { "fn-knock": { "command": "python", "args": ["-m", "fn_knock_mcp.server"] } } } ``` > **Note**: The HMAC secret is resolved at startup via env file or auto-detection — do NOT put it in mcp.json. ### 4. (Optional) Configure HTTP Proxy If fn-knock needs to reach external services (GitHub API, DNS providers, etc.) and you're behind a proxy: ```bash export HTTP_PROXY=http://192.168.31.21:7890 export HTTPS_PROXY=http://192.168.31.21:7890 ``` ## Available Tools (58 total) ### Dashboard - `fnknock_dashboard_stats` — Traffic/auth/threat stats (configurable time range) - `fnknock_realtime_traffic` — Current real-time bytes in/out ### Config & Run Mode - `fnknock_get_config` — Full gateway config - `fnknock_update_run_type` — Switch mode: direct / reverse_proxy / subdomain_proxy / tunnel - `fnknock_sync_routes` — Trigger immediate route reload ### Reverse Proxy (Host Mappings) - `fnknock_get_host_mappings` — List all host → target rules - `fnknock_add_host_mapping` — Add a reverse proxy rule - `fnknock_delete_host_mapping` — Remove a rule by host ### Stream / Tunnel - `fnknock_get_stream_mappings` — List port mappings - `fnknock_update_stream_mappings` — Replace all stream mappings - `fnknock_frp_status` / `frp_start` / `frp_stop` — FRP tunnel control - `fnknock_cloudflared_status` / `cloudflared_start` / `cloudflared_stop` ### SSL / ACME - `fnknock_ssl_status` — Certificate library status - `fnknock_acme_overview` — ACME jobs & applications - `fnknock_acme_dns_providers` — Supported DNS providers - `fnknock_acme_create_application` — Create and submit a cert request ### DDNS - `fnknock_ddns_status` — Current DDNS state and last IP - `fnknock_ddns_toggle` — Enable/disable DDNS - `fnknock_ddns_save_config` — Save provider config - `fnknock_ddns_test` — Test connectivity and detect public IP ### Auth & Security - `fnknock_get_auth_settings` — Auth settings (session timeout, 2FA) - `fnknock_get_totp_status` — TOTP 2FA status - `fnknock_totp_setup` — Initiate TOTP enrollment - `fnknock_totp_bind` — Complete TOTP binding - `fnknock_passkey_list` — List registered passkeys ### IP Management - `fnknock_whitelist_list` / `whitelist_add` / `whitelist_delete` - `fnknock_ip_lookup` — Batch IP geolocation lookup (up to 20 IPs) ### Scanner / Security - `fnknock_scanner_settings` — Path scanner config - `fnknock_scanner_blacklist` — Blocked suspicious IPs - `fnknock_scanner_toggle` — Enable/disable scanner protection ### Logs & Events - `fnknock_get_events` — System event log (filterable) - `fnknock_delete_events` — Delete events by ID - `fnknock_gateway_logs_dates` — Dates with gateway logs - `fnknock_gateway_logs_entries` — Access logs for a date ### Notifications - `fnknock_notifications_providers` — Notification channels - `fnknock_notifications_rules` — Notification rules - `fnknock_notifications_triggers` — Historical notification trigger records (可按 status/rule_id 筛选) - [REDACTED_SECRET] — Historical delivery records (可按 status/provider_id/rule_id/trigger_id 筛选) - [REDACTED_SECRET] — Clear delivery records (不传参数则清空全部) ### Gateway & Network - `fnknock_gateway_settings` / `gateway_update` - `fnknock_gateway_visibility` — Regional visibility config - `fnknock_system_reset_firewall` — Reset firewall for a run type - `fnknock_system_dnsmasq_status` — DNS proxy status ### Sessions & Terminal - `fnknock_sessions_list` — Active user sessions - `fnknock_session_kick` — Kick a session - `fnknock_terminal_status` / `terminal_sessions` — tmux management - `fnknock_backoff_list` / `backoff_reset` — Rate limit state ### Maintenance - `fnknock_backup_export` / `backup_import` - `fnknock_update_check` — Check for fn-knock updates - `fnknock_traffic_stats` — Traffic statistics ## Finding Your HMAC Secret If fn-knock is running, open its web UI at http://localhost:7998 and check: - Browser DevTools → Network tab → any API request → look for `x-timestamp`, `x-nonce`, `x-signature` headers - Or search the page source for `__FN_KNOCK_HMAC_SECRET__` The secret is a 64-char hex string. Create the credentials file with it: ```bash mkdir -p ~/.config/fn-knock echo [REDACTED_SECRET] \ > ~/.config/fn-knock/credentials ``` ## Troubleshooting **"Missing Required Security Headers"** → HMAC secret is wrong or not resolved. Check env var or credentials file. **"Request Expired or Time Desynced"** → System clock is out of sync. Run `timedatectl set-ntp true` on Linux. **MCP not loading in OpenClaw** → Verify Python path: `which python` and confirm `mcp` package is installed there. → Check OpenClaw logs: `openclaw logs` for MCP initialization errors. **Port 7998 unreachable** → fn-knock may be bound to a different interface. Check its listen address in the config.


Security scan verdicts — ClawScan: suspicious | static analysis: clean | VirusTotal: clean | SkillSpector: clean (LOW)