Pirsch MCP Server
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@Pirsch MCP Server Show me my top pages for the last 30 days"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
Pirsch MCP Server
A read-only Model Context Protocol server for the Pirsch Analytics API v1, written in TypeScript.
The server uses the official pirsch-sdk and exposes no tracking or configuration writes.
Installation
Requirements: Node.js 22.19 or later and a Pirsch OAuth client with read scopes.
Most MCP clients can run the package on demand without a global installation. Add the following server configuration, replacing the credential placeholders:
{
"mcpServers": {
"pirsch": {
"command": "npx",
"args": ["-y", "@charpeni/pirsch-mcp"],
"env": {
"PIRSCH_CLIENT_ID": "your-client-id",
"PIRSCH_CLIENT_SECRET": "your-client-secret"
}
}
}
}Alternatively, install the executable globally:
npm install --global @charpeni/pirsch-mcpThen configure your MCP client to run pirsch-mcp.
Create an OAuth client from the Pirsch dashboard's Integration Settings or Account Settings. Disable write operations to keep its scopes read-only. Pirsch access keys beginning with pa_ are write-only and cannot read statistics.
Related MCP server: umami-mcp-server
Tools
pirsch_list_domains
Lists every domain available to the configured OAuth client. Each result contains only the fields needed to select a statistics target: id, hostname, and optional displayName and timezone values.
Account-scoped OAuth clients can use this tool to discover all accessible domains. Agents can switch domains by passing the selected id as domainId to pirsch_query_statistics.
pirsch_get_domain
Returns the Pirsch SDK's default domain. Dashboard-scoped clients return their dashboard domain. Account-scoped clients can access multiple domains, so use the Pirsch dashboard to select the intended PIRSCH_DOMAIN_ID.
pirsch_query_statistics
Queries traffic, pages, events, acquisition, device, geography, tag, keyword, and funnel statistics.
Available metrics:
total, visitors, pages, entry_pages, exit_pages, session_duration,
time_on_page, conversion_goals, events, event_metadata, event_list,
event_pages, growth, active_visitors, time_of_day, languages, referrers,
operating_systems, operating_system_versions, browsers, browser_versions,
countries, regions, cities, platforms, screen_classes, utm_sources,
utm_mediums, utm_campaigns, utm_contents, utm_terms, tag_keys, tags,
keywords, funnelsExample:
{
"metric": "pages",
"from": "2026-07-01",
"to": "2026-07-31",
"limit": 10,
"sort": "visitors",
"direction": "desc"
}The domainId argument can be omitted when PIRSCH_DOMAIN_ID is configured. The server never automatically selects a domain for statistics queries because account-scoped clients can access multiple domains.
A typical multi-domain flow is:
Call
pirsch_list_domains.Match the requested hostname or display name.
Pass that domain's
idtopirsch_query_statistics.
Configuration
Environment variable | Required | Default | Description |
| Yes | Pirsch OAuth client ID | |
| Yes | Pirsch OAuth client secret | |
| No | Default domain ID; otherwise pass | |
| No |
| Hostname passed to the SDK; unused by reads |
| No |
| Pirsch API base URL |
| No |
| Positive request timeout in milliseconds |
Credentials are loaded lazily. MCP clients can start the server and list its tools without credentials, but tool calls require them.
MCP Inspector
Set the required credentials in your shell:
export PIRSCH_CLIENT_ID="your-client-id"
export PIRSCH_CLIENT_SECRET="your-client-secret"Inspect the published package:
npx -y @modelcontextprotocol/inspector \
-e "PIRSCH_CLIENT_ID=$PIRSCH_CLIENT_ID" \
-e "PIRSCH_CLIENT_SECRET=$PIRSCH_CLIENT_SECRET" \
npx -y @charpeni/pirsch-mcpInspector does not forward arbitrary shell variables to spawned stdio servers, so the credentials are passed explicitly with -e.
Development
Install dependencies and run the complete quality gate:
pnpm install
pnpm checkList the local server's tools through Inspector without Pirsch credentials:
pnpm inspect:listRun the local Inspector web UI after exporting the credentials:
pnpm inspectOther development commands:
pnpm dev
pnpm build
pnpm format
pnpm lint
pnpm typecheck
pnpm testAvailable Tools
3 toolspirsch_get_domainA
Return the Pirsch SDK's default domain. Dashboard-scoped clients return their dashboard domain. Account-scoped clients may have additional domains and should select one explicitly for statistics queries.
Inputs: no named parameters.
pirsch_list_domainsA
List every Pirsch domain available to the configured OAuth client. Returns safe domain summaries for selecting domainId in statistics queries.
Inputs: no named parameters.
pirsch_query_statisticsA
Read Pirsch Analytics v1 statistics for a domain and date range. Pass domainId from pirsch_list_domains to query a specific domain. Supports traffic, pages, events, acquisition, devices, geography, tags, keywords, and funnels.
Inputs: to (required), from (required), metric (required), tag, +35 more.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 3 tools
Each tool has a clearly distinct role: get_domain returns the default, list_domains enumerates available domains, and query_statistics fetches analytics. No overlap or ambiguity exists.
All tool names follow a consistent pattern of 'pirsch_' prefix plus a verb_noun structure (get, list, query). This makes the API predictable and easy to understand.
Three tools is well-scoped for an analytics server: domain discovery, default selection, and statistics querying. Each tool is necessary and there is no bloat.
The tool surface fully covers the workflow of selecting a domain and querying comprehensive statistics (traffic, pages, events, etc.). No obvious missing operations or dead ends exist for the stated purpose.
Maintenance
Related MCP Connectors
Read-only Google Analytics 4 MCP server for AI assistants.
Read-only Google Search Console MCP server for AI assistants.
Hosted MCP server for live public-data APIs and Skills for AI agents.
Hosted MCP server for GA4, Google Ads and Search Console. Google OAuth, nothing to install.
Related MCP Servers
- AlicenseAqualityDmaintenanceMCP server that provides read access to Plausible Analytics data with natural-language date resolution, enabling users to query analytics like 'yesterday' or 'last week' without needing to know exact date formats.8MIT
- AlicenseNot gradedqualityDmaintenanceMCP server for Umami Analytics that provides read-only tools to query website stats, events, sessions, reports, and more, enabling natural language analytics queries.12 npm3MIT
- AlicenseAqualityDmaintenanceA read-only MCP server for Umami analytics, enabling natural language queries of website stats, traffic trends, events, sessions, and analytics reports.1310 npm1Elastic 2.0
- AlicenseAqualityCmaintenanceEnables natural language analytics queries for Pirsch Analytics, providing comprehensive website traffic statistics, period comparisons, and trend analysis through an MCP interface.454 npm1MIT