{"_id":"@charpeni/pirsch-mcp","_rev":"2-4973025525fc67b626d2642848eea957","name":"@charpeni/pirsch-mcp","dist-tags":{"latest":"1.0.0"},"versions":{"0.1.0":{"name":"@charpeni/pirsch-mcp","version":"0.1.0","license":"MIT","_id":"@charpeni/pirsch-mcp@0.1.0","maintainers":[{"name":"charpeni","email":"nicolas.charpentier079@gmail.com"}],"bin":{"pirsch-mcp":"dist/src/index.js"},"dist":{"shasum":"fd66a09fd2fd1eee8ca1edcc2da79b4894f53e3c","tarball":"https://registry.npmjs.org/@charpeni/pirsch-mcp/-/pirsch-mcp-0.1.0.tgz","fileCount":8,"integrity":"sha512-mPnJCu0xqU4HV1tqlEIkEmWxgKnMMTwXokW3sI72jsGpBEyaNpHCntgt6uKTYK6KrARIb+ZE1xFhD7k+Lieyag==","signatures":[{"sig":"MEQCIA45V2TO5JNreqVQeBbHDhiZLhWgpLfK/C74OlrEbOZ6AiB6EWi92INNZDDxsUdKNYt+sIiyi+dR0BzITKdZ6rb1Sg==","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":23054},"type":"module","engines":{"node":">=22.19.0"},"exports":{"./package.json":"./package.json"},"gitHead":"ee3a834ff0f94144aa7adb4ea1b8148e255500cf","scripts":{"dev":"node src/index.ts","lint":"oxlint src test","test":"pnpm build && node --test dist/test/*.test.js","build":"tsc -p tsconfig.json","check":"pnpm format:check && pnpm lint && pnpm typecheck && pnpm test","start":"node dist/src/index.js","format":"oxfmt --write .","inspect":"pnpm build && HOST=127.0.0.1 mcp-inspector -e \"PIRSCH_CLIENT_ID=$PIRSCH_CLIENT_ID\" -e \"PIRSCH_CLIENT_SECRET=$PIRSCH_CLIENT_SECRET\" node dist/src/index.js","prepack":"pnpm check","typecheck":"tsc -p tsconfig.json --noEmit","format:check":"oxfmt --check .","inspect:list":"pnpm build && mcp-inspector --cli node dist/src/index.js -- --method tools/list"},"_npmUser":{"name":"charpeni","email":"nicolas.charpentier079@gmail.com"},"_npmVersion":"10.9.8","description":"MCP server for Pirsch Analytics","directories":{},"_nodeVersion":"22.22.3","dependencies":{"zod":"^4.4.3","pirsch-sdk":"2.9.1","@modelcontextprotocol/server":"^2.0.0"},"publishConfig":{"access":"public"},"_hasShrinkwrap":false,"packageManager":"pnpm@11.15.1","devDependencies":{"oxfmt":"0.61.0","oxlint":"1.76.0","typescript":"7.0.2","@types/node":"^26.1.2","@modelcontextprotocol/client":"^2.0.0","@modelcontextprotocol/inspector":"^2.0.0"},"_npmOperationalInternal":{"tmp":"tmp/pirsch-mcp_0.1.0_1785613414687_0.3872440514388664","host":"s3://npm-registry-packages-npm-production"}},"1.0.0":{"name":"@charpeni/pirsch-mcp","version":"1.0.0","description":"MCP server for Pirsch Analytics","license":"MIT","repository":{"type":"git","url":"git+https://github.com/charpeni/pirsch-mcp.git"},"bin":{"pirsch-mcp":"dist/src/index.js"},"type":"module","exports":{"./package.json":"./package.json"},"publishConfig":{"access":"public"},"scripts":{"build":"tsc -p tsconfig.json","check":"pnpm format:check && pnpm lint && pnpm typecheck && pnpm test","dev":"node src/index.ts","format":"oxfmt --write .","format:check":"oxfmt --check .","inspect":"pnpm build && HOST=127.0.0.1 mcp-inspector -e \"PIRSCH_CLIENT_ID=$PIRSCH_CLIENT_ID\" -e \"PIRSCH_CLIENT_SECRET=$PIRSCH_CLIENT_SECRET\" node dist/src/index.js","inspect:list":"pnpm build && mcp-inspector --cli node dist/src/index.js -- --method tools/list","lint":"oxlint src test","prepack":"pnpm check","start":"node dist/src/index.js","test":"pnpm build && node --test dist/test/*.test.js","typecheck":"tsc -p tsconfig.json --noEmit"},"dependencies":{"@modelcontextprotocol/server":"^2.0.0","pirsch-sdk":"^2.10.1","zod":"^4.4.3"},"devDependencies":{"@modelcontextprotocol/client":"^2.0.0","@modelcontextprotocol/inspector":"^2.0.0","@types/node":"^26.1.2","oxfmt":"0.61.0","oxlint":"1.76.0","typescript":"7.0.2"},"engines":{"node":">=22.19.0"},"packageManager":"pnpm@11.15.1","gitHead":"07041419464208220393406bd86239cee43adaf0","_id":"@charpeni/pirsch-mcp@1.0.0","bugs":{"url":"https://github.com/charpeni/pirsch-mcp/issues"},"homepage":"https://github.com/charpeni/pirsch-mcp#readme","_nodeVersion":"24.18.0","_npmVersion":"12.0.2","dist":{"integrity":"sha512-qjAd+X0pjP1Z+S8UDijYNEoUStwkEwfpJAfPYy6wGiIUdOF1/FGxWfOJLskWnuINbVGR40wQkNNcttljV1dptg==","shasum":"bcd3b54b2685ffe379e0e07be41e93ac363129b6","tarball":"https://registry.npmjs.org/@charpeni/pirsch-mcp/-/pirsch-mcp-1.0.0.tgz","fileCount":8,"unpackedSize":23158,"attestations":{"url":"https://registry.npmjs.org/-/npm/v1/attestations/@charpeni%2fpirsch-mcp@1.0.0","provenance":{"predicateType":"https://slsa.dev/provenance/v1"}},"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEUCIF3CZqQqE48sOwm+BvAqdmjfpt2EeWvG3c124+28F0H1AiEAmWspPn92f+B1TxiVOzpk2pUMIVImZmLI93LNafzbbX0="}]},"_npmUser":{"name":"GitHub Actions","email":"npm-oidc-no-reply@github.com","trustedPublisher":{"id":"github","oidcConfigId":"oidc:0d9d12c3-2b5b-45b6-80af-4f926639603c"}},"directories":{},"maintainers":[{"name":"charpeni","email":"nicolas.charpentier079@gmail.com"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/pirsch-mcp_1.0.0_1785851679268_0.13810019754480019"},"_hasShrinkwrap":false}},"time":{"created":"2026-08-01T19:43:34.467Z","modified":"2026-08-04T13:54:40.461Z","0.1.0":"2026-08-01T19:43:34.832Z","1.0.0":"2026-08-04T13:54:39.423Z"},"license":"MIT","description":"MCP server for Pirsch Analytics","maintainers":[{"name":"charpeni","email":"nicolas.charpentier079@gmail.com"}],"readme":"# Pirsch MCP Server\n\nA read-only [Model Context Protocol](https://modelcontextprotocol.io/) server for the [Pirsch Analytics API v1](https://docs.pirsch.io/api-sdks/api-guide-v1), written in TypeScript.\n\nThe server uses the official [`pirsch-sdk`](https://github.com/pirsch-analytics/pirsch-js-sdk) and exposes no tracking or configuration writes.\n\n## Installation\n\nRequirements: Node.js 22.19 or later and a Pirsch OAuth client with read scopes.\n\nMost MCP clients can run the package on demand without a global installation. Add the following server configuration, replacing the credential placeholders:\n\n```json\n{\n  \"mcpServers\": {\n    \"pirsch\": {\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"@charpeni/pirsch-mcp\"],\n      \"env\": {\n        \"PIRSCH_CLIENT_ID\": \"your-client-id\",\n        \"PIRSCH_CLIENT_SECRET\": \"your-client-secret\"\n      }\n    }\n  }\n}\n```\n\nAlternatively, install the executable globally:\n\n```bash\nnpm install --global @charpeni/pirsch-mcp\n```\n\nThen configure your MCP client to run `pirsch-mcp`.\n\nCreate 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.\n\n## Tools\n\n### `pirsch_list_domains`\n\nLists 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.\n\nAccount-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`.\n\n### `pirsch_get_domain`\n\nReturns 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`.\n\n### `pirsch_query_statistics`\n\nQueries traffic, pages, events, acquisition, device, geography, tag, keyword, and funnel statistics.\n\nAvailable metrics:\n\n```text\ntotal, visitors, pages, entry_pages, exit_pages, session_duration,\ntime_on_page, conversion_goals, events, event_metadata, event_list,\nevent_pages, growth, active_visitors, time_of_day, languages, referrers,\noperating_systems, operating_system_versions, browsers, browser_versions,\ncountries, regions, cities, platforms, screen_classes, utm_sources,\nutm_mediums, utm_campaigns, utm_contents, utm_terms, tag_keys, tags,\nkeywords, funnels\n```\n\nExample:\n\n```json\n{\n  \"metric\": \"pages\",\n  \"from\": \"2026-07-01\",\n  \"to\": \"2026-07-31\",\n  \"limit\": 10,\n  \"sort\": \"visitors\",\n  \"direction\": \"desc\"\n}\n```\n\nThe `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.\n\nA typical multi-domain flow is:\n\n1. Call `pirsch_list_domains`.\n2. Match the requested hostname or display name.\n3. Pass that domain's `id` to `pirsch_query_statistics`.\n\n## Configuration\n\n| Environment variable   | Required | Default                 | Description                                  |\n| ---------------------- | -------- | ----------------------- | -------------------------------------------- |\n| `PIRSCH_CLIENT_ID`     | Yes      |                         | Pirsch OAuth client ID                       |\n| `PIRSCH_CLIENT_SECRET` | Yes      |                         | Pirsch OAuth client secret                   |\n| `PIRSCH_DOMAIN_ID`     | No       |                         | Default domain ID; otherwise pass `domainId` |\n| `PIRSCH_HOSTNAME`      | No       | `localhost`             | Hostname passed to the SDK; unused by reads  |\n| `PIRSCH_BASE_URL`      | No       | `https://api.pirsch.io` | Pirsch API base URL                          |\n| `PIRSCH_TIMEOUT_MS`    | No       | `5000`                  | Positive request timeout in milliseconds     |\n\nCredentials are loaded lazily. MCP clients can start the server and list its tools without credentials, but tool calls require them.\n\n## MCP Inspector\n\nSet the required credentials in your shell:\n\n```bash\nexport PIRSCH_CLIENT_ID=\"your-client-id\"\nexport PIRSCH_CLIENT_SECRET=\"your-client-secret\"\n```\n\nInspect the published package:\n\n```bash\nnpx -y @modelcontextprotocol/inspector \\\n  -e \"PIRSCH_CLIENT_ID=$PIRSCH_CLIENT_ID\" \\\n  -e \"PIRSCH_CLIENT_SECRET=$PIRSCH_CLIENT_SECRET\" \\\n  npx -y @charpeni/pirsch-mcp\n```\n\nInspector does not forward arbitrary shell variables to spawned `stdio` servers, so the credentials are passed explicitly with `-e`.\n\n## Development\n\nInstall dependencies and run the complete quality gate:\n\n```bash\npnpm install\npnpm check\n```\n\nList the local server's tools through Inspector without Pirsch credentials:\n\n```bash\npnpm inspect:list\n```\n\nRun the local Inspector web UI after exporting the credentials:\n\n```bash\npnpm inspect\n```\n\nOther development commands:\n\n```bash\npnpm dev\npnpm build\npnpm format\npnpm lint\npnpm typecheck\npnpm test\n```\n","readmeFilename":"README.md","homepage":"https://github.com/charpeni/pirsch-mcp#readme","repository":{"type":"git","url":"git+https://github.com/charpeni/pirsch-mcp.git"},"bugs":{"url":"https://github.com/charpeni/pirsch-mcp/issues"}}