企业官网建设流程全解析

WebMCP CLI命令是使用 WebMCP 的全部入口。WebMCP 是一个让任意网站把 tools、resources、prompts 共享给你本地 LLM 客户端（Claude Desktop、Cursor、Cline、Windsurf 等）的开源项目，它通过一个只运行在 localhost 的 WebSocket 桥接服务器（默认端口 4797）实现连接。这篇文章就是它的WebMCP CLI 命令完全指南：8 个开关逐个讲清楚，新手照着敲命令即可上手。

一、WebMCP CLI 是做什么的？

先用一句话理解它的工作方式：

MCP 客户端 → MCP Server → WebSocket Server → 你的网页（工具在这里执行）→ 结果按原路返回

也就是说，CLI 命令负责三件事：

1. 搭建本地桥接服务（后台常驻的 WebSocket 服务器）
2. 向 MCP 客户端写配置（把 WebMCP 注册进你的 AI 工具）
3. 签发一次性连接令牌（把网站接进来）

所有命令都通过npx直接运行，无需提前安装：

npx -y @jason.today/webmcp@latest [选项]

二、8 个 CLI 开关总览表

以下清单来自源码中的参数解析逻辑 src/websocket-server.js：

| 短参数 | 开关 | 作用 | 常见场景 | | :--: | :--: | -- | -- | | — |--config| 自动把 WebMCP 写入 MCP 客户端配置 | 首次安装（最常用） | |-p|--port| 指定端口号，默认 4797 | 端口冲突时 | |-q|--quit| 停止后台服务 | 关闭 WebMCP | |-n|--new| 生成新的网站连接令牌 | 接入一个网站 | |-c|--clean| 清除所有已授权令牌 | 重新开始时 | |-f|--foreground| 前台运行，不转入后台 | 调试、看日志 | |-m|--mcp| 启动内置 MCP Server | 写在客户端配置里 | |-d|--docker| 声明服务跑在 Docker 里 | 容器部署 | |-h|--help| 显示帮助信息 | 忘了参数时 |

三、逐个开关详解

1️⃣--config：一键配置 MCP 客户端（最常用）

首次使用只需要这一条命令，WebMCP 会自动找到对应客户端的配置文件并写入连接信息：

npx -y @jason.today/webmcp@latest --config claude

内置支持 4 种客户端：claude、cline、cursor、windsurf。如果传入的不是这四个名字，程序会把它当作一个JSON 配置文件的路径来处理，因此任何支持 MCP 配置格式的工具都能接入。

💡 注意：部分客户端（如 Claude Desktop）写入配置后需要重启才能看到新工具。

客户端配置路径映射逻辑见 src/config.js。

2️⃣--new：生成网站连接令牌

要让某个 WebMCP 网站接入你的 AI，需要一张"入场券"——连接令牌：

npx -y @jason.today/webmcp@latest --new

命令会输出一段CONNECTION TOKEN，把它粘贴到网站右下角蓝色小方块提供的输入框中即可。这张令牌是一次性的：网站用它注册后立即作废，网站会拿到自己独立的会话令牌。

也可以直接让模型替你调用内置的"令牌生成"工具，效果相同；如果你不想让模型看到令牌内容，就手动执行--new。

令牌生成逻辑见 src/websocket-server.js。

3️⃣--mcp：启动 MCP Server（写给客户端配置的）

这个开关一般不用你手动敲，它由--config自动写入客户端配置。写入的内容形如：npx -y @jason.today/webmcp@latest --mcp，作用是以 MCP Server 身份常驻，等待 AI 客户端通过本地端口连入。

手动体验完整流程可以执行：

npx -y @jason.today/webmcp@latest --mcp

4️⃣--port：修改监听端口

默认端口是4797。如果你的电脑上该端口被占用（Docker 部署时同理，见 docker-compose.yml），可以换一个：

npx -y @jason.today/webmcp@latest --port 8080

端口必须是 1~65535 之间的数字，否则命令会报错退出。

5️⃣--quit：停止后台服务

WebMCP 默认以守护进程（daemon）方式在后台运行，通过 PID 文件管理。要关闭它：

npx -y @jason.today/webmcp@latest --quit

没有运行中的服务时会提示No running server found，不用担心报错。停止逻辑见 src/websocket-server.js。

6️⃣--clean：清除所有已授权令牌

当你想"推倒重来"（比如换了一台电脑、或网站授权混乱了）：

npx -y @jason.today/webmcp@latest --clean

该命令会清空本地保存的全部"频道-令牌"配对。如果服务正在运行，需要再重启一次服务才能生效。令牌存储逻辑见 src/tokens.js。

7️⃣--foreground：前台运行

默认情况下服务会 fork 到后台。加上--foreground（或短参数-f）则不进入后台，方便你直接看到实时日志、按 Ctrl+C 结束：

npx -y @jason.today/webmcp@latest --foreground

调试端口冲突、连接失败等问题时，这是最实用的开关。

8️⃣--docker：声明 Docker 部署

如果你用容器方式跑 WebSocket 服务器（项目自带 Dockerfile 和 docker-compose.yml），在客户端配置中同时加上--docker，WebMCP 会认为服务已在容器里运行，直接通过 WebSocket 连入，而不是再启动一个本地进程。

四、速查：典型操作命令清单

把下面几段收藏起来，日常基本够用：

| 操作 | 命令 | | -- | -- | | 首次安装（以 Claude 为例） |npx -y @jason.today/webmcp@latest --config claude| | 生成网站令牌 |npx -y @jason.today/webmcp@latest --new| | 换端口启动 |npx -y @jason.today/webmcp@latest --port 8080| | 前台调试 |npx -y @jason.today/webmcp@latest --foreground| | 清除所有授权 |npx -y @jason.today/webmcp@latest --clean| | 停止服务 |npx -y @jason.today/webmcp@latest --quit| | 查看帮助 |npx -y @jason.today/webmcp@latest --help|

等价的原生node启动方式见 package.json 中的 scripts（start-daemon、stop-daemon、start-mcp-client等）。

五、配置存在哪里？

所有配置统一存放在用户主目录的~/.webmcp下（目录创建与文件定义见 src/config.js）：

• .webmcp-server.pid：后台服务的进程号
• .env：自动生成的服务器内部令牌
• .webmcp-tokens.json：所有已授权网站的频道-令牌记录

需要"干净重装"时，执行--clean+--quit即可，无需手改这些文件。

六、新手常见问题

Q1：令牌可以重复使用吗？不行。--new生成的注册令牌在网站完成注册后立即销毁，每个网站只对应一张会话令牌。

Q2：为什么 AI 里看不到新网站的工具？依次检查：① 网站页面是否显示已连接（绿勾状态）；② MCP 客户端是否重启过；③ 用--foreground看日志确认服务在运行。

Q3：连接会自动断开吗？会。网页端 5 分钟无操作会自动断开并收起面板，属于安全设计（超时逻辑见 src/webmcp.js）。

Q4：这个项目符合 W3C 官方规范吗？需要注意：本仓库是 WebMCP 的早期提案实现，用于验证"网站即 MCP 服务器"的价值，并不符合后来演进出的 W3C 官方规范。完整背景说明见 README.md。

写在最后

掌握--config（安装）、--new（接网站）、--quit（退出）三个高频开关，WebMCP 的核心使用流程就跑通了；其余 5 个开关（--mcp、--port、--clean、--foreground、--docker）分别对应调参与运维场景，按需查阅即可。祝使用愉快！