Goatcounter MCP Server

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

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

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

    

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

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)

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

  node --version
  

Step 2: Locate Claude Desktop Configuration

- 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

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

Step 5: Verify Connection

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.

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.

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.

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.

    GOATCOUNTER_CODE=your_site_code

    GOATCOUNTER_API_KEY=your_goatcounter_api_key

    

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 LICENSE file for details.