Goatcounter MCP Server

基本能力

产品定位

Goatcounter MCP Server 是一个中间件服务，旨在为语言模型和 MCP 客户端提供与 Goatcounter 网站分析 API 交互的标准化接口。

核心功能

• 提供大多数 Goatcounter API 端点的工具接口
• 通过环境变量（GOATCOUNTER_API_KEY、GOATCOUNTER_CODE）配置 API 密钥和站点代码
• 延迟初始化 API 客户端：即使未配置 API 凭据，也可以列出工具
• 速率限制处理：在遇到 API 速率限制（HTTP 429）时实现自动重试和回退
• 优先使用 X-Rate-Limit-Reset 头信息进行等待
• 如果头信息不可用或无效，则使用指数回退（从 1 秒开始）和随机抖动
• 最多重试 5 次
• 直接使用 fastmcp 命令行工具运行

适用场景

• 需要集成 Goatcounter 数据分析功能的语言模型应用
• 需要自动化获取网站统计信息的开发项目
• 需要标准化接口访问 Goatcounter API 的 MCP 客户端

工具列表

1. Goatcounter_get_me：获取当前 Goatcounter 用户和 API 密钥的信息
2. Goatcounter_list_sites：列出当前 API 密钥可访问的所有 Goatcounter 站点
3. Goatcounter_list_paths：获取站点跟踪路径的概览（无统计信息）
4. Goatcounter_get_stats_total：获取指定时间段内站点的总页面浏览量和独立访客数
5. Goatcounter_get_stats_hits：列出页面统计数据（每个路径的页面浏览量和访客数）
6. Goatcounter_get_stats_refs：列出引荐来源统计数据
7. Goatcounter_get_stats_browsers：列出浏览器统计数据
8. Goatcounter_get_stats_systems：列出操作系统统计数据
9. Goatcounter_get_stats_sizes：列出屏幕尺寸统计数据
10. Goatcounter_get_stats_locations：列出位置统计数据

常见问题解答

• 如何配置 API 密钥和站点代码？通过设置 GOATCOUNTER_API_KEY 和 GOATCOUNTER_CODE 环境变量
• 如何处理 API 速率限制？服务会自动实现重试和回退机制
• 如何与 Claude Desktop 集成？通过配置 claude_desktop_config.json 文件

使用教程

使用依赖

• Python 环境
• Node.js（用于与 Claude Desktop 集成）

安装教程

选项1：通过 Smithery 安装（推荐）

npx -y @smithery/cli install @rafaljanicki/goatcounter-mcp-server --client claude

选项2：从 PyPI 安装

pip install goatcounter-mcp-server

选项3：从源代码安装

1. 克隆仓库：

git clone https://github.com/rafaljanicki/goatcounter-mcp-server
cd goatcounter-mcp-server

1. 创建虚拟环境：

python3.13 -m venv venv
source venv/bin/activate  # Windows 使用 `venv\Scripts\activate`

1. 安装依赖：

pip install -r requirements.txt

1. 配置环境变量：

cp .env.example .env

然后编辑 .env 文件添加您的 Goatcounter 详细信息

调试方式

运行服务器

从 PyPI 安装：

goatcounter-mcp-server

从源代码安装：

fastmcp dev src/goatcounter_mcp_server/server.py

验证连接

1. 重启 Claude Desktop
2. 查看输入区域是否有锤子或连接器图标
3. 点击图标查看可用的 goatcounter-mcp-server 工具

许可证

该项目遵循 MIT 开源许可条款，请参阅 MIT 了解完整条款。