goatcounter-mcp-server

goatcounter-mcp-server

0
research_and_data

The Goatcounter MCP Server is designed to facilitate interactions with the Goatcounter web analytics API through a standardized interface. It supports various API endpoints, handles authentication via environment variables, and implements rate-limiting features. The server is suitable for integration with tools like Claude Desktop using the FastMCP library.

Goatcounter MCP Server

smithery badge

Overview

This project provides a Model Context Protocol (MCP) server for interacting with the Goatcounter web analytics API. It allows language models or other MCP clients to easily query Goatcounter statistics and information using a standardized tool interface.

The server is built using Python and the FastMCP library. It reads your Goatcounter site code and API key from environment variables for authentication.

Features

  • Provides tools for most Goatcounter API endpoints.
  • Handles API key and site code configuration via environment variables (GOATCOUNTER_API_KEY, GOATCOUNTER_CODE).
  • Lazy initialization of the API client: Tools can be listed even if API credentials are not yet configured.
  • Rate Limit Handling: Implements automatic retries with backoff when encountering API rate limits (HTTP 429).
    • Prioritizes the X-Rate-Limit-Reset header for waiting if provided by the API.
    • Falls back to exponential backoff (starting at 1 second) with random jitter if the header is unavailable or invalid.
    • Retries up to 5 times before failing.
  • Runs directly using the fastmcp command-line tool.

Installation

Option 1: Installing via Smithery (Recommended)

To install X (Twitter) MCP server for Claude Desktop automatically via Smithery:

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

Option 2: Install from PyPI

The easiest way to install goatcounter-mcp-server is via PyPI:

pip install goatcounter-mcp-server

Or install directly from the repository:

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

Option 3: Install from Source

If you prefer to install from the source repository:

  1. Clone the repository:

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

  2. Create a virtual environment:

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

  3. Install dependencies: Install FastMCP and other required packages:

    pip install -r requirements.txt

  4. Configure environment variables: Copy the example .env.example file to .env:

    cp .env.example .env

    Edit the .env file and add your Goatcounter details (see Environment Variables section below).

Environment Variables

The server requires the following environment variables to be set:

  • GOATCOUNTER_CODE: Your Goatcounter site code (the subdomain part, e.g., 'mycoolsite').
  • GOATCOUNTER_API_KEY: Your Goatcounter API token. You can generate one in your Goatcounter site under Settings -> API tokens. Ensure it has the necessary permissions for the API actions you intend to use.

You can set these variables directly in your environment or place them in a .env file in the project root.

Running the Server

Option 1: Using the CLI Script

The project defines a CLI script goatcounter-mcp-server.

If installed from PyPI:

goatcounter-mcp-server

If installed from source with uv:

uv run goatcounter-mcp-server

Option 2: Using FastMCP Directly (Source Only)

If you installed from source and prefer to run the server using FastMCP's development mode:

fastmcp dev src/goatcounter_mcp_server/server.py

Using with Claude Desktop

To use this MCP server with Claude Desktop, you need to configure Claude to connect to the server. Follow these steps:

Step 1: Install Node.js

Claude Desktop uses Node.js to run MCP servers. If you don't have Node.js installed:

  • Download and install Node.js from nodejs.org.
  • Verify installation: 
    node --version

Step 2: Locate Claude Desktop Configuration

Claude Desktop uses a claude_desktop_config.json file to configure MCP servers.

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

If the file doesn't exist, create it.

Step 3: Configure the MCP Server

Edit claude_desktop_config.json to include the goatcounter-mcp-server server. Replace /path/to/goatcounter-mcp-server with the actual path to your project directory (if installed from source) or the path to your Python executable (if installed from PyPI).

If installed from PyPI:

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

If installed from source with 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": Uses the CLI script directly if installed from PyPI.
  • "env": If installed from PyPI, you may need to provide environment variables directly in the config (since there's no .env file). If installed from source, the .env file will be used.
  • "env": {"PYTHONUNBUFFERED": "1"}: Ensures output is unbuffered for better logging in Claude.

Step 4: Restart Claude Desktop

  • Quit Claude Desktop completely.
  • Reopen Claude Desktop to load the new configuration.

Step 5: Verify Connection

  • Open Claude Desktop.
  • Look for a hammer or connector icon in the input area (bottom right corner). This indicates MCP tools are available.
  • Click the icon to see the available tools from goatcounter-mcp-server

API Documentation: Available Tools

The following MCP tools are available:

Tool: Goatcounter_get_me

Get information about the current Goatcounter user and API key associated with the configured GOATCOUNTER_API_KEY.

  • Parameters: None
  • Returns: object - Information about the user and token.

Tool: Goatcounter_list_sites

List all Goatcounter sites accessible with the current API key.

  • Parameters: None
  • Returns: object - A list of accessible sites.

Tool: Goatcounter_list_paths

Get an overview of paths tracked on this site (without statistics).

  • Parameters:
    • limit (integer, optional): Limit number of returned results (1-200, default 20).
    • after (integer, optional): Only select paths after this path ID, for pagination.
  • Returns: object - A list of paths and pagination info.

Tool: Goatcounter_get_stats_total

Get the total number of pageviews and unique visitors for the site within a specified period.

  • Parameters:
    • start (string, optional): Start date (YYYY-MM-DD or relative e.g., '7 days ago').
    • end (string, optional): End date (YYYY-MM-DD or relative e.g., 'yesterday').
    • filter (string, optional): Filter paths (e.g., '/blog*').
    • daily (boolean, optional): Show daily statistics instead of totals (default: false).
  • Returns: object - Total statistics or daily statistics if daily is true.

Tool: Goatcounter_get_stats_hits

List page statistics (pageviews and visitors per path).

  • Parameters:
    • start (string, optional): Start date (YYYY-MM-DD or relative e.g., '7 days ago').
    • end (string, optional): End date (YYYY-MM-DD or relative e.g., 'yesterday').
    • filter (string, optional): Filter paths (e.g., '/blog*').
    • daily (boolean, optional): Show daily statistics instead of totals (default: false).
    • limit (integer, optional): Limit number of returned results (1-200, default 20).
    • after (integer, optional): Pagination cursor.
  • Returns: object - A list of path statistics and pagination info.

Tool: Goatcounter_get_stats_refs

List referrer statistics.

  • Parameters:
    • start (string, optional): Start date (YYYY-MM-DD or relative e.g., '7 days ago').
    • end (string, optional): End date (YYYY-MM-DD or relative e.g., 'yesterday').
    • filter (string, optional): Filter paths (e.g., '/blog*').
    • daily (boolean, optional): Show daily statistics instead of totals (default: false).
    • limit (integer, optional): Limit number of returned results (1-200, default 20).
    • after (integer, optional): Pagination cursor.
  • Returns: object - A list of referrer statistics and pagination info.

Tool: Goatcounter_get_stats_browsers

List browser statistics.

  • Parameters:
    • start (string, optional): Start date (YYYY-MM-DD or relative e.g., '7 days ago').
    • end (string, optional): End date (YYYY-MM-DD or relative e.g., 'yesterday').
    • filter (string, optional): Filter paths (e.g., '/blog*').
    • daily (boolean, optional): Show daily statistics instead of totals (default: false).
    • limit (integer, optional): Limit number of returned results (1-200, default 20).
    • after (integer, optional): Pagination cursor.
  • Returns: object - A list of browser statistics and pagination info.

Tool: Goatcounter_get_stats_systems

List operating system statistics.

  • Parameters:
    • start (string, optional): Start date (YYYY-MM-DD or relative e.g., '7 days ago').
    • end (string, optional): End date (YYYY-MM-DD or relative e.g., 'yesterday').
    • filter (string, optional): Filter paths (e.g., '/blog*').
    • daily (boolean, optional): Show daily statistics instead of totals (default: false).
    • limit (integer, optional): Limit number of returned results (1-200, default 20).
    • after (integer, optional): Pagination cursor.
  • Returns: object - A list of OS statistics and pagination info.

Tool: Goatcounter_get_stats_sizes

List screen size statistics.

  • Parameters:
    • start (string, optional): Start date (YYYY-MM-DD or relative e.g., '7 days ago').
    • end (string, optional): End date (YYYY-MM-DD or relative e.g., 'yesterday').
    • filter (string, optional): Filter paths (e.g., '/blog*').
    • daily (boolean, optional): Show daily statistics instead of totals (default: false).
    • limit (integer, optional): Limit number of returned results (1-200, default 20).
    • after (integer, optional): Pagination cursor.
  • Returns: object - A list of screen size statistics and pagination info.

Tool: Goatcounter_get_stats_locations

List location statistics.

  • Parameters:
    • start (string, optional): Start date (YYYY-MM-DD or relative e.g., '7 days ago').
    • end (string, optional): End date (YYYY-MM-DD or relative e.g., 'yesterday').
    • filter (string, optional): Filter paths (e.g., '/blog*').
    • daily (boolean, optional): Show daily statistics instead of totals (default: false).
    • limit (integer, optional): Limit number of returned results (1-200, default 20).
    • after (integer, optional): Pagination cursor.
  • Returns: object - A list of location statistics and pagination info.

Usage

  1. Set Environment Variables: Create a .env file in your project root or set the environment variables directly:

    GOATCOUNTER_CODE=your_site_code
GOATCOUNTER_API_KEY=your_goatcounter_api_key

    You can generate an API key in your Goatcounter account settings.

  2. Run with FastMCP: Integrate this server with your FastMCP setup. Refer to the FastMCP documentation for details on connecting MCP servers.

    The server registers tools with the prefix Goatcounter (e.g., Goatcounter.list_sites).

Development

  • Install development dependencies: pip install -e ".[dev]" (if dev dependencies are specified in pyproject.toml)
  • This project uses hatch for building.

Contributing

Contributions are welcome! Please open an issue or submit a pull request.

License

This project is licensed under the MIT License - see the file for details.