内容
# changedetection-mcp
一个适用于 [changedetection.io](https://changedetection.io) 的 [MCP](https://modelcontextprotocol.io) 服务器 - 直接从任何兼容MCP的AI客户端（VS Code Copilot、Claude Desktop、Cursor等）控制你的实例。无需克隆或本地构建。
## 快速开始
无需安装。 将以下配置添加到你的MCP客户端，它将通过 `npx` 自动获取并运行。
### VS Code（用户级，跨机器同步）
将以下内容添加到你的用户级MCP配置（`Preferences: Open User Settings (JSON)` → `mcp` 键，或 `~/.config/Code/User/mcp.json`）：
```json
{
"servers": {
"changedetection": {
"type": "stdio",
"command": "npx",
"args": ["--prefer-online", "-y", "github:mrshappy0/changedetection-mcp"],
"env": {
"CHANGEDETECTION_URL": "http://your-instance:5000",
"CHANGEDETECTION_API_KEY": "${input:changedetection-api-key}"
}
}
}
}
```
> `${input:changedetection-api-key}` 变量导致VS Code在每个会话中提示一次密钥，因此它永远不会接触磁盘。
>
> `--prefer-online` 告诉 npx 在启动前始终检查 GitHub 的最新提交，以便您在每次重启时自动获取更新，而无需清除 npx 缓存。
### Claude Desktop
将以下内容添加到 `~/Library/Application Support/Claude/claude_desktop_config.json`（macOS）或 `%APPDATA%\Claude\claude_desktop_config.json`（Windows）：
```json
{
"mcpServers": {
"changedetection": {
"command": "npx",
"args": ["--prefer-online", "-y", "github:mrshappy0/changedetection-mcp"],
"env": {
"CHANGEDETECTION_URL": "http://your-instance:5000",
"CHANGEDETECTION_API_KEY": "your-api-key"
}
}
}
}
```
### 环境变量
| 变量 | 必需 | 描述 |
|---|---|---|
| `CHANGEDETECTION_URL` | 是 | 您的 changedetection.io 实例的基本 URL（例如 `http://192.168.1.100:5000`） |
| `CHANGEDETECTION_API_KEY` | 是 | changedetection.io UI 中 **设置 → API** 中的 API 密钥 |
---
## 工具
### 系统
| 工具 | 描述 |
|---|---|
| `get_system_info` | 系统状态、运行时间、版本、监视计数 |
### 监视管理
| 工具 | 描述 |
|---|---|
| `list_watches` | 列出所有监视，可选按标签或强制重新检查过滤 |
| `search_watches` | 按 URL 或标题搜索监视 |
| `create_watch` | 创建一个新的页面监视，支持完整字段 |
| `get_watch` | 获取单个监视的完整详细信息 |
| `update_watch` | 更新现有监视的任何字段（部分更新） |
| `delete_watch` | 删除监视及其所有历史记录 |
| `set_watch_state` | 暂停/取消暂停或静音/取消静音监视 |
| `import_watches` | 批量导入 URL 列表作为新监视 |
### 快照和差异
| 工具 | 描述 |
|---|---|
| `get_watch_history` | 列出监视的所有历史快照 |
| `get_watch_snapshot` | 检索特定快照的内容 |
| `get_watch_diff` | 差异任意两个快照（文本、HTML 或 Markdown） |
### 标签
| 工具 | 描述 |
|---|---|
| `list_tags` | 列出所有标签 |
| `create_tag` | 创建新标签 |
| `update_tag` | 重命名或更新标签 |
| `delete_tag` | 删除标签 |
### 通知
| 工具 | 描述 |
|---|---|
| `get_notifications` | 获取全局通知 URL 列表 |
| `add_notifications` | 将 URL 追加到全局通知列表 |
| `replace_notifications` | 替换整个全局通知列表 |
| `send_test_notification` | 发送测试通知以验证投递 |
---
## 监视字段
`create_watch` 和 `update_watch` 都支持以下字段：
| 字段 | 类型 | 描述 |
|---|---|---|
| `url` | 字符串 | 要监视的 URL |
| `title` | 字符串 | 人性化标签 |
| `fetch_backend` | 枚举 | `html_requests`（快速，无 JS）、`html_webdriver`（Selenium）、`system` |
| `processor` | 枚举 | `text_json_diff`（常规）或 `restock_diff`（价格/库存跟踪） |
| `include_filters` | 字符串[] | CSS/XPath 选择器 - 仅监视匹配元素 |
| `subtractive_selectors` | 字符串[] | CSS/XPath 选择器，用于 **剥离** 差异前的内容（适用于移除时间戳、广告等） |
| `ignore_text` | 字符串[] | 差异中要忽略的正则表达式/文本模式 |
| `trigger_text` | 字符串[] | 仅当其中一个模式匹配时才发送通知 |
| `llm_intent` | 字符串 | 应触发警报的更改的纯英文描述（AI 过滤） |
| `conditions` | 对象[] | 高级条件规则对象 |
| `conditions_match_logic` | 枚举 | `ALL` 或 `ANY`（默认为 `ALL`） |
| `time_between_check` | 对象 | 例如 `{"hours": 4}` 或 `{"minutes": 30}` |
| `notification_urls` | 字符串[] | 按监视的 [Apprise](https://github.com/caronc/apprise) 通知 URL |
| `notification_title` | 字符串 | 自定义通知标题（支持 `{{watch_url}}` 等） |
| `notification_body` | 字符串 | 自定义通知正文（支持 `{{diff}}`、`{{current_snapshot}}` 等） |
| `notification_muted` | 布尔值 | 静音此监视的通知 |
| `paused` | 布尔值 | 暂停监视 |
| `webdriver_delay` | 数字 | 页面加载后等待捕获的秒数 |
| `webdriver_js_execute_code` | 字符串 | 在捕获前在浏览器中运行的 JavaScript 代码 |
| `browser_steps` | 对象[] | Playwright 样式的自动化步骤 |
| `tags` | 字符串[] | 要分配的标签 UUID |
| `track_ldjson_price_data` | 布尔值 | 启用 JSON-LD 价格提取 |
| `price_change_min` | 数字 | \*（restock_diff）当价格低于此值时提醒 |
| `price_change_max` | 数字 | \*（restock_diff）当价格高于此值时提醒 |
| `price_change_threshold_percent` | 数字 | \*（restock_diff）触发警报所需的最小百分比变化 |
---
## 本地开发
需要 [pnpm](https://pnpm.io/)。
```bash
git clone https://github.com/mrshappy0/changedetection-mcp.git
cd changedetection-mcp
pnpm install
```
复制并填写您的环境：
```bash
cp .env.example .env # 或手动创建 .env
```
```
CHANGEDETECTION_URL=http://localhost:5000
CHANGEDETECTION_API_KEY=your-api-key
```
直接运行服务器（无需构建步骤）：
```bash
pnpm dev # 使用 tsx 进行快速迭代
pnpm start # 使用 node --experimental-strip-types
```
构建编译输出：
```bash
pnpm build # 输出到 dist/ 并注入 shebang
```
`dist/` 目录已提交到仓库，以便 `npx github:mrshappy0/changedetection-mcp` 无需在消费者端进行构建步骤即可工作。
### TypeScript / Node 类型
项目需要在 `tsconfig.json` 中的 `compilerOptions.types` 下显式列出 `@types/node`：
```json
"types": ["node"]
```
仓库中已配置此项。 如果在修改 `tsconfig.json` 后出现 `Cannot find name 'process'` 错误，请确保此项存在。
---
## 依赖项
| 包 | 版本 | 备注 |
|---|---|---|
| `@modelcontextprotocol/sdk` | `^1.12.0` | MCP 服务器 SDK |
| `zod` | `^4.4.3` | 模式验证 - 使用 `z.record(keySchema, valueSchema)`（Zod v4 API） |
