Click on "Install 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.
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.
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: plausible-whenever-mcp
pirsch_list_domainsLists 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_domainReturns 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_statisticsQueries 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 id to pirsch_query_statistics.
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.
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.
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 testReturn 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.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the behavioral disclosure burden. It reveals the key behavioral nuance: the default domain returned depends on client scope. It does not discuss edge cases or side effects, but for a read-only getter, the scope explanation adds meaningful transparency.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences, front-loaded with the core purpose and then adding scope context. Every sentence earns its place with no redundancy or fluff.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a no-argument getter, the description is reasonably complete: it explains what is returned, how it varies by scope, and provides usage guidance. It could explicitly mention pirsch_list_domains for the account-scoped case, but the sibling tool list already provides that context.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool has zero parameters, so the schema inherently covers everything. The description adds no parameter details because there are none to add; the baseline of 4 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's function: 'Return the Pirsch SDK's default domain.' It also distinguishes scope-dependent behavior (dashboard-scoped vs account-scoped) and references statistics queries, separating it from siblings pirsch_list_domains and pirsch_query_statistics.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives clear context: dashboard-scoped clients can use this directly, while account-scoped clients 'should select one explicitly for statistics queries.' This implies when not to use it, though it does not explicitly name the alternative tool (pirsch_list_domains).
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List every Pirsch domain available to the configured OAuth client. Returns safe domain summaries for selecting domainId in statistics queries.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden. 'List' implies a read-only operation, but 'safe domain summaries' is vague and does not disclose details like rate limits, errors, or any side effects. The transparency is adequate but not rich, so a score of 3 is appropriate.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two concise sentences, front-loaded with the action ('List every Pirsch domain'), and every phrase adds value. No fluff or repetition.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple list tool with no parameters and no output schema, the description is fairly complete. It explains the purpose (domain selection for statistics queries) and the scope (domains available to the OAuth client). Some details about the return format are absent, but the simplicity keeps the bar low.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool has zero parameters, so the baseline is 4. The description correctly provides no parameter information since none exists, and there is no gap to compensate for.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses the specific verb 'List' and names the resource 'every Pirsch domain', clearly showing the tool's purpose. It also adds context about the OAuth client and the intended use for selecting domainId in statistics queries, which distinguishes it from sibling tools like pirsch_get_domain and pirsch_query_statistics.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies when to use the tool: before querying statistics, to obtain domainId values. It does not explicitly mention alternatives, but the context of the sibling tools and the stated purpose provide clear guidance on its usage without needing exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
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.
| Name | Required | Description | Default |
|---|---|---|---|
| to | Yes | Inclusive end date in YYYY-MM-DD format. | |
| tag | No | ||
| city | No | ||
| from | Yes | Inclusive start date in YYYY-MM-DD format. | |
| path | No | ||
| sort | No | ||
| tags | No | ||
| event | No | ||
| limit | No | ||
| scale | No | ||
| start | No | Query the previous N seconds. Primarily useful for active visitors. | |
| metric | Yes | The Pirsch statistic to return. | |
| offset | No | ||
| region | No | ||
| search | No | ||
| browser | No | ||
| country | No | ISO-3166 Alpha-2 country code. | |
| pattern | No | RE2-compatible page path pattern. | |
| utmTerm | No | ||
| domainId | No | Pirsch domain ID, typically selected with pirsch_list_domains. Falls back to PIRSCH_DOMAIN_ID. | |
| exitPath | No | ||
| language | No | ISO-639-1 language code. | |
| platform | No | ||
| referrer | No | ||
| timezone | No | IANA timezone, for example Europe/Berlin. | |
| direction | No | ||
| entryPath | No | ||
| eventMeta | No | ||
| utmMedium | No | ||
| utmSource | No | ||
| utmContent | No | ||
| screenClass | No | ||
| utmCampaign | No | ||
| eventMetaKey | No | ||
| referrerName | No | ||
| customMetricKey | No | ||
| operatingSystem | No | ||
| customMetricType | No | ||
| includeAverageTimeOnPage | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description must carry the burden of behavioral disclosure. It only states 'Read', indicating a non-mutating operation, but provides no details on authentication, rate limits, pagination, or output behavior. For a complex analytics tool, this is insufficient.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences long, front-loaded with the core purpose, and every clause adds value. It avoids redundancy and is efficiently structured for quick comprehension.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's complexity (39 parameters, no output schema, no annotations), the description is far from complete. It does not explain return values, how the various filters interact, or what the 'scale' parameter controls. The description only provides a high-level overview, leaving important context missing.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is only 23%, and the description adds little to compensate. It explains that domainId comes from pirsch_list_domains and lists high-level metric categories, but the 39 parameters, including many unannotated filters, remain unexplained. The description adds limited meaning beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states it reads Pirsch Analytics v1 statistics for a domain and date range, with a specific verb ('Read') and resource. It also lists the supported metric categories (traffic, pages, events, etc.), which differentiates it from sibling tools like pirsch_list_domains and pirsch_get_domain.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides a clear prerequisite: 'Pass domainId from pirsch_list_domains to query a specific domain.' This establishes when the tool is used and how to obtain the required domain ID. It doesn't explicitly mention alternatives or exclusions, but the sibling tools are distinct enough that usage context is clear.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recent tool additions, removals, and schema changes observed during successful MCP inspections. Dates show when Glama detected each change.
v0.1.0pirsch_get_domainpirsch_list_domainspirsch_query_statisticsEach 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.
Unclaimed servers have limited discoverability.
If you are the server author, to access and configure the admin panel.
Hosted MCP server for live public-data APIs and Skills for AI agents.
Clamp Analytics MCP server: traffic, revenue, funnels, cohorts, errors, and search, for AI agents.
MCP server for querying and analyzing data from ad platforms, analytics tools, and spreadsheets
Read-only MCP server for turva.dev, an agent-readiness audit and advisory service.
We provide all the information about MCP servers via our MCP API.
curl -X GET 'https://glama.ai/api/mcp/v1/servers/charpeni/pirsch-mcp'
If you have feedback or need assistance with the MCP directory API, please join our Discord server
