Goatcounter MCP Server

What is Goatcounter MCP Server?

Goatcounter MCP Server is a Model Context Protocol server that exposes the Goatcounter web analytics API as standardized tools. It enables language models or other MCP clients to query site statistics, page data, referrers, browsers, operating systems, screen sizes, and locations.

How to use Goatcounter MCP Server?

Install via PyPI (pip install goatcounter-mcp-server) or from source. Set the GOATCOUNTER_CODE and GOATCOUNTER_API_KEY environment variables (in a .env file or directly). Run the server with the goatcounter-mcp-server command. For Claude Desktop, add a corresponding entry to claude_desktop_config.json.

Key features of Goatcounter MCP Server

• Provides tools for most Goatcounter API endpoints.
• Handles API key and site code configuration via environment variables.
• Lazy initialization: tools can be listed before credentials are set.
• Automatic retries with backoff on HTTP 429 rate limits (up to 5 retries).
• Runs directly using the fastmcp command-line tool.

Use cases of Goatcounter MCP Server

• Query total pageviews and unique visitors over a custom date range.
• List most‑visited pages with optional path filtering.
• Analyze referrer, browser, operating system, screen size, and location statistics.
• Paginate through large sets of paths, stats, or referrers.
• Retrieve current user or API token information and list accessible sites.

FAQ from Goatcounter MCP Server

What environment variables are required?

The server requires GOATCOUNTER_CODE (your Goatcounter site subdomain) and GOATCOUNTER_API_KEY (an API token generated under Settings → API tokens).

How does rate limit handling work?

The server automatically retries requests that receive a 429 response. It first respects the X-Rate-Limit-Reset header, falling back to exponential backoff with random jitter starting at 1 second, up to 5 retries.

Can I list the available tools without an API key?

Yes. The server uses lazy initialization, so tools can be listed even if GOATCOUNTER_CODE or GOATCOUNTER_API_KEY are not yet configured.

How do I install Goatcounter MCP Server?

It can be installed via Smithery (npx -y @smithery/cli install @rafaljanicki/goatcounter-mcp-server --client claude), from PyPI (pip install goatcounter-mcp-server), or directly from the GitHub repository.

How do I configure it for Claude Desktop?

Edit claude_desktop_config.json to add a goatcounter-mcp-server entry with the command (e.g., goatcounter-mcp-server) and environment variables under env. Then restart Claude Desktop.