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:

Option 2: Install from PyPI

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

Or install directly from the repository:

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:

If installed from source with uv:

Option 2: Using FastMCP Directly (Source Only)

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

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:

If installed from source with uv:

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