fn-knock MCP Server

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

pip install mcp requests
# or with uv
uv tool install fn-knock-mcp  # (if published to PyPI)

If installing from source:

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 — 环境变量（推荐）

export FN_KNOCK_HMAC_SECRET="your-secret-here"

方式 B — 凭证文件

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):

{
  "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:

{
  "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:

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 筛选)
• fnknock_notifications_deliveries — Historical delivery records (可按 status/provider_id/rule_id/trigger_id 筛选)
• fnknock_notifications_deliveries_clear — 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:

mkdir -p ~/.config/fn-knock
echo "HMAC_SECRET=42e0a9e578284ad8313752293a3079680b377c249e0e3306527442b363a4cd78" \
  > ~/.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.