Goatcounter

You can run a dedicated MCP server to access Goatcounter analytics through a standardized tool interface. This makes it easy to query site statistics, paths, and various breakdowns from language models or other MCP clients, with built-in handling for authentication and rate limits.

How to use

You connect to the Goatcounter MCP Server by running one of the provided MCP entry points and then querying the available tools. The server exposes tools to list sites, fetch overall stats, and drill into per-path, referrer, browser, OS, screen size, and location statistics. Authentication is supplied via environment variables containing your Goatcounter site code and API key. When you start the server, keep it running so your MCP client can send requests and receive structured results.

How to install

# Prerequisites
- Python 3.11+ (or a compatible Python environment)
- Optional: Node.js if you plan to use Claude Desktop tooling for MCP servers

# Option A: Install from PyPI (recommended for quick setup)
pip install goatcounter-mcp-server

# Option B: Install from source (development approach)
# 1) Clone the repository
# 2) Create and activate a virtual environment
# 3) Install dependencies
pip install -r requirements.txt

# Option C: Install via Smithery (for Claude Desktop integration)
npx -y @smithery/cli install @rafaljanicki/goatcounter-mcp-server --client claude
```} ,{

Running the server

Choose one of the runtime methods below and start the MCP server. Ensure your Goatcounter credentials are configured via environment variables before starting.

# Option 1: Run the CLI script if installed from PyPI
goatcounter-mcp-server

# Option 2: Run via uv when using the source (dev mode)
uv run goatcounter-mcp-server

# Option 3: Run directly with FastMCP in development mode (source)
fastmcp dev src/goatcounter_mcp_server/server.py
```}]} ,{

Set the required environment variables in your shell or a .env file in the project root. The server uses these to authenticate with Goatcounter.

Configuration and environment

Define these environment variables to authorize access to Goatcounter:

GOATCOUNTER_CODE=your_site_code
GOATCOUNTER_API_KEY=your_goatcounter_api_key
```}]} ,{

Place them in a .env file in the project root or export them in your shell before starting the server.

Using with Claude Desktop

If you use Claude Desktop, configure the MCP server so Claude can access the Goatcounter tools. Specify the command to start the server and the environment variables shown above. Claude will present the available tools once the server is running.

Available tools overview

The server exposes a range of tools for Goatcounter statistics, including getting current user information, listing sites, and retrieving page, referrer, browser, OS, screen size, and location statistics. Each tool returns structured data suitable for ingestion by MCP clients.

Available tools

Goatcounter_get_me

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

Goatcounter_list_sites

List all Goatcounter sites accessible with the current API key.

Goatcounter_list_paths

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

Goatcounter_get_stats_total

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

Goatcounter_get_stats_hits

List page statistics (pageviews and visitors per path).

Goatcounter_get_stats_refs

List referrer statistics.

Goatcounter_get_stats_browsers

List browser statistics.

Goatcounter_get_stats_systems

List operating system statistics.

Goatcounter_get_stats_sizes

List screen size statistics.

Goatcounter_get_stats_locations

List location statistics.