How do I install the goatcounter mcp server?

Run it through your MCP client's configuration using `npx -y @smithery/cli`. Add the server block to Claude Desktop's config file (or use `claude mcp add` for Claude Code), restart the client, and the tools appear automatically. Full snippets are on this page.

What credentials does it need?

It reads `PYTHONUNBUFFERED`, `GOATCOUNTER_CODE`, `GOATCOUNTER_API_KEY` from the environment. Store these in your client's env block or a secrets manager — never commit them to a repository — and grant the narrowest scope that still covers your use case.

Goatcounter MCP Server — Install Guide & Tools

Name: Goatcounter MCP Server
Author: rafaljanicki

What is the Goatcounter MCP server?

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. Exposed over MCP by the goatcounter mcp server, that capability becomes something an assistant can invoke while it works, not something you go and do afterwards.

What it actually does

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

Adding it to your client

Installation goes through your MCP client rather than a global install: point it at @smithery/cli on npm and it is fetched when the client starts. The copy-paste blocks for Claude Desktop, Claude Code and Cursor are further down this page.

Configuration

You will need 3 environment variables: PYTHONUNBUFFERED, GOATCOUNTER_CODE, GOATCOUNTER_API_KEY. The server will not start without them, which is usually why the tools fail to appear on a first run. Keep credentials in your client's env block or a secrets manager rather than in a file you might commit.

When to reach for it

Among the developer tooling options, the useful question is rarely "what can it do" but "what does it cost you to run" — permissions, credentials, and how much of your context its toolset consumes. It is maintained by rafaljanicki; worth a glance at recent repository activity before you build anything load-bearing on it.

This entry was verified against Goatcounter's own documentation before publication; SyncDev keeps the directory reviewed rather than auto-generated.

Caveats

It runs with your machine's permissions. That is convenient and also the reason to think about what you point it at before you approve a tool call.
Missing credentials fail quietly in some clients — if no tools show up, check the environment block first.
MCP clients confirm each tool call by default. Leave that on until you have watched what the goatcounter mcp server does with a few real requests.

How to install the Goatcounter MCP server

If installed from source with `uv`:
```json
{
  "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"
      }
    }
  }
}

Configuration as documented by the project. Restart the client after saving.

Configuration

Variable	Description	Required
PYTHONUNBUFFERED	Configuration value read at startup.	Optional
GOATCOUNTER_CODE	Configuration value read at startup.	Optional
GOATCOUNTER_API_KEY	Credential the server authenticates with.	Yes

Frequently asked questions

It connects Goatcounter to MCP-compatible AI assistants such as Claude and Cursor. Instead of copying data back and forth by hand, the assistant works with Goatcounter directly.

Goatcounter MCP Server

What is the Goatcounter MCP server?

What it actually does

Adding it to your client

Configuration

When to reach for it

Caveats

How to install the Goatcounter MCP server

Configuration

Frequently asked questions

Alternatives to the Goatcounter MCP server

Context7

Playwright

GitHub

Linear

Git

Time

Goatcounter MCP Server

What is the Goatcounter MCP server?

What it actually does

Adding it to your client

Configuration

When to reach for it

Caveats

How to install the Goatcounter MCP server

Configuration

Frequently asked questions

What does the goatcounter mcp server do?

How do I install the goatcounter mcp server?

What credentials does it need?

Alternatives to the Goatcounter MCP server

Context7

Playwright

GitHub

Linear

Git

Time