Goatcounter MCP Server

Goatcounter MCP 服务

概述

此项目提供了一个用于与 Goatcounter 网站分析 API 交互的 Model Context Protocol（MCP）服务。它允许大模型或其他 MCP 客户端通过标准化的工具接口轻松查询 Goatcounter 统计数据和信息。

该服务使用 Python 和 FastMCP 库构建。它通过环境变量读取 Goatcounter 站点代码和 API 密钥以进行身份验证。

功能

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

安装

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

通过 Smithery 自动为 Claude Desktop 安装 X（Twitter）MCP 服务：

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

选项 2：从 PyPI 安装

安装 goatcounter-mcp-server 最简单的方法是通过 PyPI：

pip install goatcounter-mcp-server

或直接从代码仓库安装：

pip install git+https://github.com/rafaljanicki/goatcounter-mcp-server.git

选项 3：从源代码安装

如果你希望从源代码仓库安装：

1. 克隆代码仓库：

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

2. 创建虚拟环境：

   python3.13 -m venv venv
   source venv/bin/activate  # On Windows use `venv\Scripts\activate`
   

3. 安装依赖项： 安装 FastMCP 和其他必需的程序包：

   pip install -r requirements.txt
   

4. 配置环境变量： 将示例文件 .env.example 复制为 .env：

   cp .env.example .env
   

   编辑 .env 文件并添加你的 Goatcounter 详细信息（参见下方的“环境变量”部分）。

环境变量

该服务需要设置以下环境变量：

• GOATCOUNTER_CODE：你的 Goatcounter 站点代码（子域名部分，例如 mycoolsite）。
• GOATCOUNTER_API_KEY：你的 Goatcounter API 令牌。你可以在 Goatcounter 站点的“Settings -> API tokens”下生成令牌。确保它具有执行你计划使用的 API 操作所需的权限。

你可以直接在环境中设置这些变量，也可以将它们放在项目根目录下的 .env 文件中。

运行服务

选项 1：使用 CLI 脚本

该项目定义了一个 CLI 脚本 goatcounter-mcp-server。

如果通过 PyPI 安装：

goatcounter-mcp-server

如果从源代码使用 uv 安装：

uv run goatcounter-mcp-server

选项 2：直接使用 FastMCP（仅限源代码安装）

如果你从源代码安装，并希望使用 FastMCP 的开发模式运行服务：

fastmcp dev src/goatcounter_mcp_server/server.py

与 Claude Desktop 搭配使用

若要在 Claude Desktop 中使用此 MCP 服务，你需要配置 Claude 以连接到该服务。请按以下步骤操作：

步骤 1：安装 Node.js

Claude Desktop 使用 Node.js 运行 MCP 服务。如果尚未安装 Node.js：

• 从 nodejs.org 下载并安装 Node.js。
• 验证安装：

  node --version
  

步骤 2：找到 Claude Desktop 配置文件

Claude Desktop 使用 claude_desktop_config.json 文件来配置 MCP 服务。

• Windows：%APPDATA%\Claude\claude_desktop_config.json
• macOS：~/Library/Application Support/Claude/claude_desktop_config.json

如果该文件不存在，请创建一个。

步骤 3：配置 MCP 服务

编辑 claude_desktop_config.json，加入 goatcounter-mcp-server 服务。如果从源码安装，请将 /path/to/goatcounter-mcp-server 替换为项目目录的实际路径；如果从 PyPI 安装，则替换为 Python 可执行文件的路径。

如果从 PyPI 安装：

{
  "mcpServers": {
    "goatcounter-mcp-server": {
      "command": "goatcounter-mcp-server",
      "args": [],
      "env": {
        "PYTHONUNBUFFERED": "1",
        "GOATCOUNTER_CODE": "goatcounter_code",
        "GOATCOUNTER_API_KEY": "goatcounter_api_key"
      }
    }
  }
}

如果使用 uv 从源码安装：

{
  "mcpServers": {
    "goatcounter-mcp-server": {
      "command": "uv",
      "args": [
        "--directory",
        "/path/to/goatcounter-mcp-server",
        "run",
        "goatcounter-mcp-server"
      ],
      "env": {
        "PYTHONUNBUFFERED": "1",
        "GOATCOUNTER_CODE": "goatcounter_code",
        "GOATCOUNTER_API_KEY": "goatcounter_api_key"
      }
    }
  }
}

• "command": "goatcounter-mcp-server"：如果从 PyPI 安装，则直接使用 CLI 脚本。
• "env"：如果从 PyPI 安装，可能需要直接在配置中提供环境变量（因为没有 .env 文件）。如果从源码安装，则会使用 .env 文件。
• "env": {"PYTHONUNBUFFERED": "1"}：确保输出不会缓冲，以便在 Claude 中更好地记录日志。

步骤 4：重启 Claude Desktop

• 完全退出 Claude Desktop。
• 重新打开 Claude Desktop 以加载新配置。

步骤 5：验证连接

• 打开 Claude Desktop。
• 在输入区域（右下角）查找锤子或连接器图标。这表示 MCP 工具已可用。
• 点击该图标，查看 goatcounter-mcp-server 提供的可用工具

API 文档：可用工具

以下 MCP 工具可用：

---

工具：Goatcounter_get_me

获取当前 Goatcounter 用户以及与配置的 GOATCOUNTER_API_KEY 关联的 API 密钥信息。

• 参数：无
• 返回：object - 用户和令牌的信息。

---

工具：Goatcounter_list_sites

列出使用当前 API 密钥可访问的所有 Goatcounter 站点。

• 参数：无
• 返回：object - 可访问站点列表。

---

工具：Goatcounter_list_paths

概览此站点跟踪的路径（不含统计信息）。

• 参数：
  • limit（integer，可选）：限制返回结果数量（1-200，默认值：20）。
  • after（integer，可选）：仅选择此路径 ID 之后的路径，用于分页。
• 返回：object - 路径列表和分页信息。

---

工具：Goatcounter_get_stats_total

获取指定时间段内站点的页面浏览量和独立访客总数。

• 参数：
  • start（string，可选）：开始日期（YYYY-MM-DD 或相对日期，例如 '7 days ago'）。
  • end（string，可选）：结束日期（YYYY-MM-DD 或相对日期，例如 'yesterday'）。
  • filter（string，可选）：筛选路径（例如 '/blog*'）。
  • daily（boolean，可选）：显示每日统计数据而非总计（默认值：false）。
• 返回：object - 总体统计数据；如果 daily 为 true，则返回每日统计数据。

---

工具：Goatcounter_get_stats_hits

列出页面统计信息（每个路径的页面浏览量和访客数）。

• 参数：
  • start（string，可选）：开始日期（YYYY-MM-DD 或相对日期，例如 '7 days ago'）。
  • end（string，可选）：结束日期（YYYY-MM-DD 或相对日期，例如 'yesterday'）。
  • filter（string，可选）：筛选路径（例如 '/blog*'）。
  • daily（boolean，可选）：显示每日统计数据而非总计（默认值：false）。
  • limit（integer，可选）：限制返回结果数量（1-200，默认值：20）。
  • after（integer，可选）：分页游标。
• 返回：object - 路径统计列表和分页信息。

---

工具：Goatcounter_get_stats_refs

列出引荐来源统计信息。

• 参数：
  • start（字符串，可选）：开始日期（YYYY-MM-DD 或相对日期，例如 '7 days ago'）。
  • end（字符串，可选）：结束日期（YYYY-MM-DD 或相对日期，例如 'yesterday'）。
  • filter（字符串，可选）：筛选路径（例如，'/blog*'）。
  • daily（布尔值，可选）：显示每日统计信息，而非总计（默认值：false）。
  • limit（整数，可选）：限制返回结果数量（1-200，默认值 20）。
  • after（整数，可选）：分页游标。
• 返回值：object - 引荐来源统计信息列表及分页信息。

---

工具：Goatcounter_get_stats_browsers

列出浏览器统计信息。

• 参数：
  • start（字符串，可选）：开始日期（YYYY-MM-DD 或相对日期，例如 '7 days ago'）。
  • end（字符串，可选）：结束日期（YYYY-MM-DD 或相对日期，例如 'yesterday'）。
  • filter（字符串，可选）：筛选路径（例如，'/blog*'）。
  • daily（布尔值，可选）：显示每日统计信息，而非总计（默认值：false）。
  • limit（整数，可选）：限制返回结果数量（1-200，默认值 20）。
  • after（整数，可选）：分页游标。
• 返回值：object - 浏览器统计信息列表及分页信息。

---

工具：Goatcounter_get_stats_systems

列出操作系统统计信息。

• 参数：
  • start（字符串，可选）：开始日期（YYYY-MM-DD 或相对日期，例如 '7 days ago'）。
  • end（字符串，可选）：结束日期（YYYY-MM-DD 或相对日期，例如 'yesterday'）。
  • filter（字符串，可选）：筛选路径（例如，'/blog*'）。
  • daily（布尔值，可选）：显示每日统计信息，而非总计（默认值：false）。
  • limit（整数，可选）：限制返回结果数量（1-200，默认值 20）。
  • after（整数，可选）：分页游标。
• 返回值：object - OS 统计信息列表及分页信息。

---

工具：Goatcounter_get_stats_sizes

列出屏幕尺寸统计信息。

• 参数：
  • start（字符串，可选）：开始日期（YYYY-MM-DD 或相对日期，例如 '7 days ago'）。
  • end（字符串，可选）：结束日期（YYYY-MM-DD 或相对日期，例如 'yesterday'）。
  • filter（字符串，可选）：筛选路径（例如，'/blog*'）。
  • daily（布尔值，可选）：显示每日统计信息，而非总计（默认值：false）。
  • limit（整数，可选）：限制返回结果数量（1-200，默认值 20）。
  • after（整数，可选）：分页游标。
• 返回值：object - 屏幕尺寸统计信息列表及分页信息。

---

工具：Goatcounter_get_stats_locations

列出地理位置统计信息。

• 参数：
  • start（字符串，可选）：开始日期（YYYY-MM-DD 或相对日期，例如 '7 days ago'）。
  • end（字符串，可选）：结束日期（YYYY-MM-DD 或相对日期，例如 'yesterday'）。
  • filter（字符串，可选）：筛选路径（例如，'/blog*'）。
  • daily（布尔值，可选）：显示每日统计信息，而非总计（默认值：false）。
  • limit（整数，可选）：限制返回结果数量（1-200，默认值 20）。
  • after（整数，可选）：分页游标。
• 返回值：object - 地理位置统计信息列表及分页信息。

用法

1. 设置环境变量： 在项目根目录中创建 .env 文件，或直接设置环境变量：

   GOATCOUNTER_CODE=your_site_code
   GOATCOUNTER_API_KEY=your_goatcounter_api_key
   

   你可以在 Goatcounter 账户设置中生成 API 密钥。

2. 使用 FastMCP 运行： 将此服务集成到你的 FastMCP 设置中。有关连接 MCP 服务的详情，请参阅 FastMCP 文档。

   此服务注册的工具均使用前缀 Goatcounter（例如，Goatcounter.list_sites）。

开发

• 安装开发依赖：pip install -e ".[dev]"（如果 pyproject.toml 中指定了开发依赖）
• 此项目使用 hatch 进行构建。

贡献

欢迎贡献！请提交 issue 或 pull request。

许可证

此项目基于 MIT License 授权，详情请参阅 LICENSE 文件。