unofficial-trackjs-mcp
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., "@unofficial-trackjs-mcp what are our top JS errors this week by affected users?"
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.
unofficial-trackjs-mcp
An MCP server that lets AI assistants (Claude Code, Claude Desktop, Cursor, and other MCP clients) query your JavaScript error data through the TrackJS Data API.
Ask things like:
"What are our top 10 JavaScript errors this week, by affected users?"
"Did errors spike after yesterday's deploy? Compare errors per page view by hour."
"Show me a few stack traces for
Cannot read properties of undefined (reading 'map').""Which pages are the most broken?"
This is an unofficial, community project. It is not made, endorsed, or supported by TrackJS. "TrackJS" is a trademark of its owner and is used here only to describe what the server connects to. For issues with this server, open an issue in this repository, not with TrackJS support.
It is read-only: it only calls the Data API's GET endpoints. It cannot change triage status, ignore rules, or any other settings.
Requirements
Node.js 18 or newer
A TrackJS API key and Customer ID. Both are only visible to the Account Owner, under Account Settings → Organization.
Related MCP server: google-analytics-mcp-server
Install
The server runs over stdio with npx, so there is nothing to install globally. It reads two environment variables:
Variable | Required | Description |
| yes | Data API key. Sent in the |
| yes | Your Customer ID, used in the API URL ( |
If either is missing, the server exits at startup with a message saying which one.
Claude Code
claude mcp add trackjs --transport stdio --env TRACKJS_API_KEY=your-api-key --env TRACKJS_CUSTOMER_ID=your-customer-id -- npx -y unofficial-trackjs-mcpPut the server name (trackjs) first and the --env options last, right before --. --env accepts several values in a row, so a name placed after it is read as another variable.
Add --scope user to make it available in every project, or --scope project to write it to a shared .mcp.json (don't commit real keys; .mcp.json supports ${TRACKJS_API_KEY} style environment expansion).
Check it with claude mcp list, or /mcp inside a session.
Claude Desktop
Edit claude_desktop_config.json (Settings → Developer → Edit Config):
{
"mcpServers": {
"trackjs": {
"command": "npx",
"args": ["-y", "unofficial-trackjs-mcp"],
"env": {
"TRACKJS_API_KEY": "your-api-key",
"TRACKJS_CUSTOMER_ID": "your-customer-id"
}
}
}
}Restart Claude Desktop afterwards. On Windows, if the server fails to start, use "command": "cmd" and "args": ["/c", "npx", "-y", "unofficial-trackjs-mcp"].
Other MCP clients (Cursor, VS Code, Windsurf, …)
Any client that supports stdio servers works. The generic shape is:
command:
npxargs:
["-y", "unofficial-trackjs-mcp"]env:
TRACKJS_API_KEY,TRACKJS_CUSTOMER_ID
For example, Cursor's .cursor/mcp.json uses the same mcpServers block as Claude Desktop above. You can also install it globally (npm install -g unofficial-trackjs-mcp) and use unofficial-trackjs-mcp as the command.
Tools
Each tool maps to one documented Data API endpoint, and the parameter names match the API (query, size, page, startDate, endDate, application, includeStack, sort).
Tool | Endpoint | What it returns |
|
| Individual error occurrences, newest first. Search with |
|
| Error counts grouped by message, with affected users, triage status, and last seen. |
|
| Error counts grouped by page URL. |
|
| Error and affected-user counts per day. |
|
| Error and affected-user counts per hour. |
|
| Page views (agent loads) per day. Useful for error rates. |
|
| Page views per hour. |
|
| Account-wide hourly usage: page views and total/processed/ignored/dropped errors. Can roll up to days. |
Common parameters:
application: limit to one TrackJS application key.startDate/endDate: ISO 8601 dates or date-times (UTC), e.g.2026-10-01or2026-10-01T14:00:00Z.page/size: paging.sizeis 1–1000; TrackJS defaults to 20.sortBy/sortDirection: on the grouped and per-period tools. The server sends them as the API'ssort=field|directionstring.
The TrackJS Data API has no endpoints for browsers, applications, or single-error lookup, so this server doesn't offer tools for them. To narrow errors by browser or anything else searchable, use list_errors with query.
Output
Results are compact JSON meant to keep the agent's context small:
Empty fields are dropped. Long messages, URLs, and metadata values are truncated with a
… [+N chars]marker.Stack traces are off unless
includeStack: true. They are then cut to the firstmaxStackLineslines (default 20), with a… N more linesnote.Every response has a
pagingblock (page,size,returned,hasMore,nextPage,totalCountwhere available). Every item has alinkto the matching TrackJS dashboard page.Time-series tools include
totals.usage_by_hourreturns rows as arrays with acolumnsheader.
Example top_messages result:
{"paging":{"page":1,"size":3,"returned":1,"hasMore":true,"nextPage":2,"startDate":"2014-09-11T00:00:00Z"},"link":"https://my.trackjs.com/messages","messages":[{"message":"Cannot read property on of undefined","count":54,"userCount":12,"status":"Investigating","lastSeen":"2016-09-22T22:42:23.579+00:00","link":"https://my.trackjs.com/messages/filtered?message=Cannot+read+property+%27on%27+of+undefined&"}]}Errors
API failures come back as tool errors written for the agent:
401: the API key was rejected. Check
TRACKJS_API_KEY.403: the key and Customer ID don't match, or the account has no Data API access.
404: usually a wrong
TRACKJS_CUSTOMER_ID.429: rate limited. Includes
Retry-Afterwhen TrackJS sends it.Timeouts (30s), network failures, 5xx, and invalid input (bad dates,
sizeout of range,startDateafterendDate) are reported the same way.
The API key is only sent in the Authorization header. It never appears in URLs, logs, or error messages.
Development
git clone https://github.com/olaj/unofficial-trackjs-mcp.git
cd unofficial-trackjs-mcp
npm install
npm run check # typecheck + lint + tests
npm run build # compiles to dist/The dev toolchain (vitest) needs Node 22+. The built package runs on Node 18+.
Tests use fixtures in test/fixtures/ shaped from the examples in the Data API docs, plus an in-memory MCP client. They make no network calls.
To try a local build in Claude Code:
npm run build
claude mcp add trackjs-dev --env TRACKJS_API_KEY=... --env TRACKJS_CUSTOMER_ID=... -- node /absolute/path/to/dist/index.jsYou can also inspect it with the MCP Inspector:
npx @modelcontextprotocol/inspector -e TRACKJS_API_KEY=... -e TRACKJS_CUSTOMER_ID=... node dist/index.jsProject layout:
src/index.ts entry point: env config + stdio transport
src/server.ts McpServer setup
src/tools.ts tool definitions (zod input schemas)
src/client.ts Data API client (built-in fetch) and error messages
src/format.ts output compaction (truncation, stack trimming, paging)
src/types.ts response types from the docsLicense
MIT © Ola. Not affiliated with TrackJS.
Available Tools
8 toolserrors_by_dayErrors per dayARead-onlyIdempotent
Daily error totals with affected-user counts and TrackJS links (GET /errors/daily), newest day first by default. Use for trends, spotting spikes and comparing before/after a deploy. Set size to the number of days you need (max 1000).
Inputs: page, size, sortBy, endDate, +3 more.
errors_by_hourErrors per hourARead-onlyIdempotent
Hourly error totals with affected-user counts and TrackJS links (GET /errors/hourly), newest hour first by default. Use to pinpoint when a spike started. Pass date-times (e.g. 2026-10-18T06:00:00Z) to narrow the window.
Inputs: page, size, sortBy, endDate, +3 more.
errors_by_urlErrors by page URLARead-onlyIdempotent
Error counts grouped by the page URL where errors happened, with affected-user counts and a TrackJS link (GET /errors/urls). Sorted by count descending by default. Use to find which pages are most broken.
Inputs: page, size, sortBy, endDate, +3 more.
list_errorsList TrackJS errorsARead-onlyIdempotent
List individual JavaScript error occurrences captured by TrackJS, newest first (GET /errors). Use query to search like the TrackJS dashboard search (matches error messages, URLs, metadata and user IDs). Each error includes message, page URL, file:line:column, browser, user/session IDs, triage status, custom metadata and a link to its TrackJS details page. Set includeStack=true to get stack traces (trimmed to maxStackLines). For 'what is breaking most' questions, call top_messages first, then use this tool with query set to a message to see examples.
Inputs: page, size, query, endDate, +4 more.
page_views_by_dayPage views per dayARead-onlyIdempotent
Daily page view counts (times the TrackJS agent loaded) newest first (GET /hits/daily). Combine with errors_by_day to compute an error rate and tell real regressions apart from traffic changes.
Inputs: page, size, endDate, startDate, +1 more.
page_views_by_hourPage views per hourARead-onlyIdempotent
Hourly page view counts (times the TrackJS agent loaded) newest first (GET /hits/hourly). Combine with errors_by_hour to see whether a spike in errors is just a spike in traffic.
Inputs: page, size, endDate, startDate, +1 more.
top_messagesTop error messagesARead-onlyIdempotent
Error counts grouped by error message, with affected-user counts, triage status, first/last seen and a TrackJS link (GET /errors/messages). Sorted by count descending by default. Best starting point for 'what are our most common / most impactful errors?'. Sort by usercount to rank by number of affected users.
Inputs: page, size, sortBy, endDate, +3 more.
usage_by_hourAccount usage per hourARead-onlyIdempotent
Account-wide usage per hour, oldest first (GET /usage/hourly): page views, total/processed/ignored/dropped errors and errors per page view. Not broken down by application. Useful for checking plan usage, ignore-rule effects and dropped (over-quota) errors. Set granularity=day to roll hours up into UTC days for long ranges. Always pass a startDate/endDate window; long hourly ranges produce many rows.
Inputs: endDate, startDate, granularity.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 8 tools
Each tool targets a distinct aggregation dimension (individual errors, by message, by URL, by day, by hour, page views, usage), and descriptions explicitly state when to prefer one over another (e.g. top_messages before list_errors). The main potential confusion is between the parallel day/hour variants and between page_views_by_hour and usage_by_hour, but the granularity/scope wording keeps them distinguishable.
Six of eight tools follow a clean resource_by_dimension pattern (errors_by_url, errors_by_day, page_views_by_hour, usage_by_hour). Two outliers use verb-first naming (list_errors, top_messages) which is readable and arguably intentional for 'list raw items' vs 'aggregate', but breaks strict uniformity.
Eight tools is well-scoped for an error-analytics server; each tool covers a distinct report shape (raw errors, groupings, time series, traffic, account usage) with no redundant entries.
The read-oriented analytics surface is solid (individual errors, groupings, daily/hourly trends, traffic for error-rate math), but triage status is only ever read, never updated, and there are no breakdowns by browser, release, or application despite such data being present in error records. Agents can answer 'what is breaking' questions but cannot manage or slice errors beyond URL/time.
Maintenance
Related MCP Connectors
Read-only MCP access to sessions, funnels, campaigns, errors, live visitors, and anomalies.
Lets AI agents analyze API metrics, request logs, and traces, and manage apps and alerts.
Query website traffic, events, signup goals, funnels, and errors with scoped Databuddy access.
Read-only website traffic, conversions, revenue, funnels and performance analytics.
Related MCP Servers
- AlicenseNot gradedqualityDmaintenanceEnables AI assistants read-only access to Sprinklr data via MCP, allowing querying reports, searching cases, and calling Sprinklr API endpoints.8 npmISC
- AlicenseAqualityBmaintenanceEnables MCP clients to query Google Analytics 4 reporting and configuration data through 27 read-only tools, including pivots, funnels, realtime reports, Admin API inspection, and diagnostics, with identifiers redacted by default.27409 npmApache 2.0
- FlicenseNot gradedqualityAmaintenanceEnables AI agents and MCP clients to query trace, session, exception, prompt, dataset, score, and metric data for enhanced debugging and observability.-
- AlicenseBqualityCmaintenanceEnables AI assistants to query application projects directly for logs, metrics, incidents, and semantic search through read-only tools.1763 npm1MIT