内容
# Clicky MCP 服务器
一个 Model Context Protocol (MCP) 服务器，暴露 [Clicky](https://clicky.com) 网络分析数据为 12 种工具，供 AI 助手使用 — 访问者数量、热门页面、流量来源、活动、跳出率、搜索词、实时访问者等。参见 [工具参考](#工具参考) 以获取完整列表。
---
## 快速开始
您需要：
- **Node.js 20+** 已安装（`node --version`）
- 一个 **Clicky 网站 ID 和 网站密钥** — 在 https://clicky.com/user/preferences/site 下的 "Info" 部分找到（您将把这些复制到本地的 `.env` 文件中，永远不要复制到聊天中）
- 一个 **支持 MCP 的 AI 代理** — Claude Code、Claude Desktop、Codex、opencode、Cursor、Cline 等
MCP 服务器由您的代理安装，而不是手动启动 — 因此最快的设置方法是交给代理。复制下面的代码块并粘贴到您的代理中：
```
为我安装 Clicky MCP 服务器。它是一个 stdio MCP 服务器，因此相同的定义适用于任何 MCP 主机（Claude Code、Claude Desktop、Codex、opencode、Cursor、Cline 等）— 使用主机自己的机制注册；只有配置格式不同，而您比本文档更了解您的主机。
1. 克隆并构建：
git clone https://github.com/colintoh/clicky-mcp.git
cd clicky-mcp && npm install && npm run build
确认构建生成了 dist/index.js。如果丢失，请停止并显示构建输出，而不是继续。
2. 在不将它们放入此聊天中的情况下设置凭证：
cp .env.example .env
然后告诉我用 Clicky 网站 ID 和 网站密钥（从 https://clicky.com/user/preferences/site 下的 "Info"）替换 clicky-mcp/.env 中的内容。不要要求我在此处粘贴密钥，也不要读取或打印 .env — 服务器在启动时加载它；密钥绝不能进入此聊天。
3. 使用此 stdio 服务器定义注册它（主机配置中不包含凭证 — 服务器从 .env 读取它们）：
命令：node 的绝对路径 — 运行 `which node`；裸 "node" 或相对路径将失败
参数：["<绝对路径>/clicky-mcp/dist/index.js"]
传输：stdio
使用主机自己的机制添加它。如果有帮助，可以使用单行引用：
- Claude Code：`claude mcp add clicky-analytics -- <node> <路径>/clicky-mcp/dist/index.js`
- JSON 主机（Claude Desktop、Cursor、Cline 等）：在 "mcpServers" 下添加一个 "clicky-analytics" 条目，包含命令 + 参数（不需要 env 块）
- Codex（~/.codex/config.toml）：[mcp_servers.clicky-analytics] 包含相同的命令 + 参数
如果主机需要重启以加载新服务器（Claude Desktop 需要完全退出 Cmd-Q，而不是仅仅关闭窗口），请告诉我执行此操作。
4. 验证：确认您的主机列出了一个 "clicky-analytics" 服务器，暴露了 12 种工具。
```
> **为什么没有 `npm start`？** MCP stdio 服务器不是独立的守护进程 — 您的代理的 MCP 主机按需将服务器作为子进程启动，并通过 stdin/stdout 与其通信。没有什么需要您自己启动，这也是为什么设置是“告诉您的代理”而不是“运行命令”。
---
## 日期参数
每个支持日期的工具接受 **明确的日期范围** 或 **Clicky 相对日期关键词** — 但不能同时使用两者：
- **明确**: `start_date` + `end_date`，均为 `YYYY-MM-DD`，范围 ≤ 31 天。
- **关键词**: `date_range`，可以是 `today`、`yesterday`、`last-7-days`、`last-30-days`、`this-week`、`last-week`、`this-month`、`last-month`、`this-year`、`last-year`。
示例：
```json
{ "date_range": "last-7-days" }
```
---
## 工具参考
所有 12 种工具，按用例大致分类。
### get_total_visitors
指定期间的总访问者数量。
- `start_date` / `end_date` **或** `date_range`
### get_actions
指定期间的总页面浏览量/操作数。
- `start_date` / `end_date` **或** `date_range`
- `limit`（数字，可选，最大 1000）
### get_bounce_rate
指定期间的跳出率和平均驻留时间。
- `start_date` / `end_date` **或** `date_range`
### get_visitors_online
实时访问者数量和分段。无需参数。
### get_top_pages
指定期间最受欢迎的页面。
- `start_date` / `end_date` **或** `date_range`
- `limit`（数字，可选，最大 1000）
### get_page_traffic
指定页面 URL 的流量数据。
- `url`（字符串，**必填**）
- `start_date` / `end_date` **或** `date_range`
### get_traffic_sources
流量来源分析 — 可选按页面 URL 过滤。
- `start_date` / `end_date` **或** `date_range`
- `page_url`（字符串，可选）— 完整 URL 或路径
### get_referring_domains
发送流量的热门来源域名。
- `start_date` / `end_date` **或** `date_range`
- `limit`（数字，可选，最大 1000）
### get_campaigns
按活动标签（`utm_campaign` 或 Clicky 活动跟踪）分组的流量。只有标记的进入流量会显示在这里 — 未标记的有机/直接流量不会。
- `start_date` / `end_date` **或** `date_range`
- `limit`（数字，可选，最大 1000）
- `include_keywords`（布尔值，可选）— 还返回活动关键词/术语标签
### get_domain_visitors
按来源域名过滤的访问者数据，带有可选分段。
- `domain`（字符串，**必填**）
- `start_date` / `end_date` **或** `date_range`
- `segments`（数组，可选）— `["pages", "visitors"]`。默认为 `["visitors"]`。
- `limit`（数字，可选，最大 1000）
### get_searches
带来访问者的热门搜索词。
- `start_date` / `end_date` **或** `date_range`
- `limit`（数字，可选，最大 1000）
### get_countries
按国家/地区划分的访问者。
- `start_date` / `end_date` **或** `date_range`
- `limit`（数字，可选，最大 1000）
---
## API 限制
由 Clicky 强制执行，非本服务器：
- 最大明确日期范围：**31 天**
- 每次请求的最大结果数：**1,000 项**
- 每个 IP 每个站点 ID 的同时请求数：1
---
## 故障排除
**"Claude Desktop 看不到服务器。"** 检查 `~/Library/Logs/Claude/mcp-server-clicky-analytics.log` 处的启动日志。最常见的原因是 `node` 不在 Claude Desktop 的 launchd PATH 上 — 通过将 `"command": "node"` 替换为 `which node` 的绝对路径来修复。第二常见的原因是忘记完全退出 Claude Desktop（`⌘Q`，而不仅仅是关闭窗口）。
**"日期范围不能超过 31 天。"** 这是 Clicky API 限制，不是我们施加的。或者缩小范围或使用 `date_range` 关键词，如 `last-30-days`。
---
## 本地开发
用于在服务器上工作，而不仅仅是使用它。
```bash
npm install # 安装依赖
npm run dev # 使用 tsx 运行，监听更改（仅用于本地测试）
npm run build # 编译 TypeScript 到 dist/
npm test # 46 个单元测试，离线，不需要凭证
npm run test:integration # 实时 API 烟雾测试（需要 .env 或环境变量）
```
凭证来自项目根目录中的 `.env` 文件 — 复制模板并填写您的值：
```bash
cp .env.example .env
```
```
CLICKY_SITE_ID=您的网站 ID
CLICKY_SITE_KEY=您的网站密钥
```
`.env` 被 gitignore，它是为 **本地开发和 MCP 主机** 提供凭证的推荐方式：它将您的密钥排除在主机配置文件和任何代理聊天之外。服务器相对于其自身位置解析 `.env`，因此无论主机启动它的工作目录如何，都可以找到它，并且只有在环境中没有凭证时才加载 `.env`。如果您愿意，可以通过主机的 `env` 块或 `--site-id`/`--site-key` 参数传递 `CLICKY_SITE_ID`/`CLICKY_SITE_KEY`。
`.githooks/pre-push` 中的预推送 git 钩子在任何更新远程 `main` 分支的推送之前自动运行 `npm test`，因此不会在不被注意的情况下发布回归。它由 `prepare` npm 脚本在 `npm install` 后自动安装。推送到功能分支不会被阻止。在紧急情况下，可以使用 `git push --no-verify` 绕过。
### 项目结构
```
clicky-mcp/
├── src/
│ ├── index.ts # MCP 服务器 + 工具调度器
│ ├── clicky-client.ts # Clicky HTTP API 客户端
│ ├── date-utils.ts # 共享日期参数生成器
│ └── tools/ # 每个工具一个文件
├── test/ # node:test 单元测试
├── scripts/verify.mjs # 实时 API 烟雾测试运行器
├── .githooks/pre-push # 为 main 自动安装测试门控
├── package.json
├── tsconfig.json
└── README.md
```
---
## License
MIT
