npm package: @masmuch/error-tracker-mcp
Description: MCP server for Error Tracker - Query and resolve errors from your terminal or IDE using AI assistants like Claude, Warp, and Cursor
Author: Masmuch
Latest version: 1.1.2

# Error Tracker MCP Server

Model Context Protocol (MCP) server for Error Tracker - Query and resolve errors directly from your terminal or IDE using AI assistants like Claude Desktop, Warp, and Cursor.

## ⚡ Quick Start

- Go to the dashboard: `https://error-tracker-web.vercel.app/`
- Create your **organization** and then a **project**
- In the project: `Settings` → `API Keys` → generate your **token** (API Key)
- Configure your MCP client:

```json
{
  "error-tracker": {
    "command": "npx",
    "args": ["-y", "@masmuch/error-tracker-mcp"],
    "env": {
      "ERROR_TRACKER_API_KEY": "et_your_api_key"
    }
  }
}
```

Note: You don’t need to set `ERROR_TRACKER_API_URL` for the hosted dashboard; it defaults automatically to the cloud service.

You can now list projects, view errors, and mark them as resolved from your assistant.

## Features

- 🔍 **List and search errors** with powerful filters (status, severity, platform, environment)
- 📊 **Get error statistics** and analytics
- 🔎 **View complete error details** including stack traces, context, and metadata
- 🔧 **Resolve errors** and update status directly from your AI assistant
- 🔗 **Find similar errors** using fingerprint matching
- 🏢 **Multi-tenant security** with organization-based access control
- 📝 **Audit logging** for compliance and tracking

## Installation

### Option 1: Install from NPM (Recommended)

```bash
npm install -g @masmuch/error-tracker-mcp
```

### Option 2: Run with npx (No installation)

```bash
npx @masmuch/error-tracker-mcp
```

### Option 3: Build from source

```bash
cd apps/mcp-server
pnpm install
pnpm build
```

## Configuration

### 1. Get your API Key

1. Go to the dashboard: `https://error-tracker-web.vercel.app/`
2. Sign in and create your **organization**
3. Create a **project** inside the organization
4. Open the project → **Settings** → **API Keys** and click "Create"
5. Copy the generated key (starts with `et_`) and save it securely (it's only shown once)

### 2. Configure your MCP Client

#### Claude Desktop

Edit `~/.config/claude/config.json` (Mac/Linux) or `%APPDATA%\Claude\config.json` (Windows):

```json
{
  "mcpServers": {
    "error-tracker": {
      "command": "npx",
      "args": ["-y", "@masmuch/error-tracker-mcp"],
      "env": {
        "ERROR_TRACKER_API_KEY": "et_your_api_key_here"
      }
    }
  }
}
```

> **Note:** `ERROR_TRACKER_API_URL` is optional and defaults to `https://error-tracker-web.vercel.app`.
> Only specify it if you're using a self-hosted instance.

#### Warp AI

Add to your Warp MCP configuration:

```json
{
  "error-tracker": {
    "command": "npx",
    "args": ["-y", "@masmuch/error-tracker-mcp"],
    "env": {
      "ERROR_TRACKER_API_KEY": "et_your_api_key_here"
    }
  }
}
```

#### Cursor

Add to your Cursor MCP settings:

```json
{
  "mcpServers": {
    "error-tracker": {
      "command": "npx",
      "args": ["-y", "@masmuch/error-tracker-mcp"],
      "env": {
        "ERROR_TRACKER_API_KEY": "et_your_api_key_here"
      }
    }
  }
}
```

### 3. Restart your client

After editing the configuration, restart Claude Desktop, Warp, or Cursor for the changes to take effect.

## Available Tools

### 1. `error-tracker_list_errors`

List errors with powerful filtering options.

**Parameters:**

- `projectId` (optional): Filter by specific project
- `status` (optional): UNRESOLVED | IN_PROGRESS | RESOLVED | IGNORED
- `severity` (optional): CRITICAL | HIGH | MEDIUM | LOW | INFO
- `environment` (optional): production, staging, development, etc.
- `platform` (optional): VERCEL, AWS_LAMBDA, NODEJS, BROWSER, etc.
- `limit` (default: 20): Number of errors to return (1-100)
- `offset` (default: 0): Pagination offset
- `orderBy` (default: lastSeen): lastSeen | firstSeen | occurrences
- `order` (default: desc): asc | desc

**Example usage:**

> "Show me the 10 most recent critical errors in production"

### 2. `error-tracker_get_error_details`

Get complete details of a specific error.

**Parameters:**

- `errorId` (required): The error ID

**Example usage:**

> "Show me the full details of error abc123"

### 3. `error-tracker_search_errors`

Search errors by text in message, stack trace, type, or filename.

**Parameters:**

- `query` (required): Search query
- `projectId` (optional): Filter by project
- `status` (optional): Filter by status
- `severity` (optional): Filter by severity
- `limit` (default: 20): Number of results

**Example usage:**

> "Search for errors containing 'null pointer'"

### 4. `error-tracker_get_error_stats`

Get error statistics and analytics.

**Parameters:**

- `projectId` (optional): Get stats for specific project
- `days` (default: 7): Number of days to include (1-90)

**Example usage:**

> "Show me error statistics for the last 30 days"

### 5. `error-tracker_list_projects`

List all accessible projects with error counts.

**Parameters:**

- `includeErrorCount` (default: true): Include count of active errors

**Example usage:**

> "What projects do I have access to?"

### 6. `error-tracker_resolve_error`

Update error status and add resolution notes.

**Parameters:**

- `errorId` (required): The error ID
- `status` (required): UNRESOLVED | IN_PROGRESS | RESOLVED | IGNORED
- `resolution` (required for RESOLVED): Notes about the resolution

**Example usage:**

> "Mark error abc123 as resolved with note 'Fixed null check in user validation'"

### 7. `error-tracker_get_similar_errors`

Find errors with similar fingerprints (same root cause).

**Parameters:**

- `errorId` (required): Reference error ID
- `limit` (default: 10): Number of similar errors (1-50)

**Example usage:**

> "Find errors similar to abc123"

## Usage Examples

### Example 1: Find and fix critical errors

```
User: What are the critical errors in my web-app project?

AI uses: error-tracker_list_projects → gets project ID
         error-tracker_list_errors (projectId, severity=CRITICAL)

AI: You have 3 critical errors:
1. TypeError: Cannot read property 'name' of undefined
   - Last seen: 2 hours ago
   - Occurrences: 42
   ...
```

### Example 2: Deep dive into an error

```
User: Show me the full stack trace for error abc123

AI uses: error-tracker_get_error_details (errorId: abc123)

AI: Here's the complete error:
- Message: Cannot read property 'name' of undefined
- File: src/components/UserProfile.tsx:45
- Stack trace: [full trace]
- User context: { id: "user_123", email: "user@example.com" }
- Request: { url: "/api/users/profile", method: "GET" }
...
```

### Example 3: Resolve an error

```
User: Mark error abc123 as resolved, I fixed the null check

AI uses: error-tracker_resolve_error (
           errorId: abc123,
           status: RESOLVED,
           resolution: "Fixed null check in UserProfile component"
         )

AI: ✅ Error abc123 has been marked as resolved.
    The audit log has been updated.
```

### Example 4: Find patterns

```
User: Are there other errors like abc123?

AI uses: error-tracker_get_similar_errors (errorId: abc123)

AI: Found 5 similar errors with the same fingerprint:
1. Error def456 - Last seen 1 hour ago
2. Error ghi789 - Last seen 3 hours ago
...

All seem to be caused by the same null pointer issue.
```

## Security

- **API Key Authentication**: All requests require a valid API key
- **Organization Isolation**: You can only access errors from your organization's projects
- **Project-Level Keys**: Optionally create API keys limited to specific projects
- **Audit Logging**: All actions are logged for compliance
- **Rate Limiting**: Protection against abuse (configurable)

## Troubleshooting

### Error: "API key is required"

Make sure `ERROR_TRACKER_API_KEY` is set in your MCP client configuration.

### Error: "Failed to connect to API"

Check your internet connection. The default API URL is `https://error-tracker-web.vercel.app`. If using a self-hosted instance, set `ERROR_TRACKER_API_URL` in your configuration.

### Error: "API key not found"

Your API key may be invalid or deleted. Generate a new one from the dashboard.

### Error: "API key is disabled"

Your API key has been disabled. Enable it in the dashboard or create a new one.

### Error: "Access denied to this project"

Your API key doesn't have access to the requested project. Check your permissions in the dashboard.

### MCP server not showing up

1. Check that your configuration file is valid JSON/YAML
2. Restart your MCP client completely
3. Check the client logs for errors
4. Try running the server manually: `npx @masmuch/error-tracker-mcp`

### Testing the server manually

You can test the server using the MCP Inspector:

```bash
npx @modelcontextprotocol/inspector npx @masmuch/error-tracker-mcp
```

This will open a web interface where you can test all tools interactively.

## Development

### Building

```bash
pnpm build
```

### Running in development

```bash
pnpm dev
```

### Testing with MCP Inspector

```bash
pnpm build
npx @modelcontextprotocol/inspector node dist/index.js
```

## Links

- [Error Tracker Dashboard](https://error-tracker-web.vercel.app)
- [SDK Documentation](https://www.npmjs.com/package/@masmuch/error-tracker-sdk)
- [MCP Protocol Specification](https://modelcontextprotocol.io)

## License

MIT

## Support

For issues or questions:

- Open an issue on GitHub
- Contact support through the dashboard
- Email: support@masmuch.com