# Axur MCP Server

A [Model Context Protocol (MCP)](https://modelcontextprotocol.io) server for the [Axur](https://axur.com) cybersecurity platform. Provides read-only access to ticket data, enabling AI assistants to search, inspect, and analyze security incidents.

## Features

- **Ticket Search & Retrieval** — filter, paginate, and fetch tickets by key
- **Ticket Details** — field values, comments, snapshots, attachments, lifecycle state, takedown options
- **Ticket Statistics** — counts by status, incidents by threat type, takedown/treatment metrics, uptime analysis, global and market-segment benchmarks

## Tools

### `tickets`
Search and retrieve tickets.

| Action | Description |
|--------|-------------|
| `list` | Search/filter tickets with pagination and sorting |
| `get` | Get a single ticket by key |
| `bulk_get` | Get multiple tickets by comma-separated keys |
| `history` | Get ticket change history |
| `types` | List all supported ticket types |

### `ticket_details`
Get detailed information for a specific ticket.

| Action | Description |
|--------|-------------|
| `fields` | Ticket field values (status, type, domain, IP, etc.) |
| `texts` | Comments, descriptions, evidence messages |
| `snapshots` | Detection snapshots (domain info, ISP, content, digital location) |
| `attachments` | List attachments for a detection |
| `lifecycle` | Available state transitions |
| `takedown` | Takedown options and eligibility |
| `timeline` | Full ticket timeline |

### `ticket_stats`
Retrieve ticket statistics and metrics.

| Action | Description |
|--------|-------------|
| `count_by_status` | Ticket count by status (requires `from`, `to`, `status`) |
| `incident_by_type` | Incidents grouped by threat type |
| `takedown_metrics` | Takedown success rate, median time to notification |
| `internal_treatment` | Internal treatment success rate and metrics |
| `takedown_uptime` | Resolution uptime distribution (buckets: <1d, 2d, 5d, etc.) |
| `treatment_uptime` | Treatment uptime distribution |
| `global_median` | Median incidents across all Axur customers (13-month trend) |
| `global_mean` | Mean incidents across all Axur customers |
| `segment_median` | Median incidents for your market segment |
| `segment_mean` | Mean incidents for your market segment |

## Setup

### Prerequisites
- Node.js 18+
- An Axur API token ([get one here](https://help.axur.com))

### Install

```bash
git clone https://github.com/Just5ky/axur-mcp.git
cd axur-mcp
npm install
npm run build
```

### Configure

```bash
cp .env.example .env
# Edit .env and add your Axur API token
```

### Usage with Claude Desktop

Add to your Claude Desktop config (`~/Library/Application Support/Claude/claude_desktop_config.json`):

```json
{
  "mcpServers": {
    "axur": {
      "command": "node",
      "args": ["/path/to/axur-mcp/dist/index.js"],
      "env": {
        "AXUR_API_TOKEN": "your_token_here"
      }
    }
  }
}
```

### Usage with other MCP clients

```bash
# Run directly
AXUR_API_TOKEN=your_token node dist/index.js
```

## Example Queries

Once connected to an AI assistant:

- *"Show me all open phishing tickets from this month"*
- *"Get details for ticket h7dw97"*
- *"What are the takedown metrics for the last 30 days?"*
- *"How do our incident numbers compare to the market segment median?"*
- *"List all ticket types supported by the platform"*

## API Coverage

This server covers the **read-only** Axur Platform ticket APIs:

- `tickets-api` — ticket search, retrieval, stats
- `tickets-core` — field values, ticket types
- `tickets-texts` — textual data (comments, evidence)
- `tickets-snapshots` — detection snapshots
- `tickets-attachments` — attachment listing
- `tickets-lifecycle` — lifecycle state inspection
- `tickets-takedown` — takedown status inspection
- `tickets-timeline` — timeline history

## Rate Limits

The Axur API enforces a rate limit of **60 requests per minute** on stats endpoints. The server surfaces 429 errors directly — plan queries accordingly.

## License

MIT