Content
# hit-mcp
An MCP server that connects an AI agent (Claude, Cursor, VS Code, etc.) to HIT — Devpeak's ticket management system. Read only: the agent can browse ticket queues, search tickets, read full ticket history, and use ticket templates — but it cannot modify any data.
## Quick start
1. Install the package globally:
```bash
npm install --global @devpeak/hit-mcp
```
2. Generate an API token in HIT: click your avatar (top right) → **Account settings** → **Security** → **API tokens** → **Create API token**.
3. Configure your MCP client with `HIT_BASE_URL` (your HIT instance, e.g. `https://support.example.com`) and `HIT_API_TOKEN` (the token from step 2). See examples below.
---
### Configuration per client
#### Claude Code
```bash
claude mcp add hit -e HIT_BASE_URL=https://your-domain-here -e HIT_API_TOKEN=your-token -- npx hit-mcp
```
#### Cursor
Add the following to `.cursor/mcp.json`:
```json
{
"mcpServers": {
"hit": {
"command": "hit-mcp",
"env": {
"HIT_BASE_URL": "https://support.example.com",
"HIT_API_TOKEN": "..."
}
}
}
}
```
#### OpenCode
Add a new key under `"mcp"` in `~/.config/opencode/opencode.jsonc`, something like:
```json
{
"mcp": {
"your-server-name": {
"type": "local",
"command": ["npx", "hit-mcp"],
"environment": {
"HIT_BASE_URL": "https://support.example.com",
"HIT_API_TOKEN": "..."
}
}
}
}
```
---
## What can the agent do?
| Tool | Description |
|---|---|
| `list_queues` | List all support queues you have access to — get an overview of which areas (IT, maintenance, administration, etc.) exist. |
| `list_tickets` | Browse and search tickets in a queue. Filter by open/closed status, search by subject, paginate. Each ticket links to HIT's web interface. |
| `get_ticket` | Fetch full details of a single ticket — description, priority, due dates, history. |
| `list_templates` | List ticket templates for a queue — useful for seeing what standard workflows are available. |
**Note:** All access is **read-only** — the agent can not create, update, or delete tickets.
## Building and developing locally
```bash
npm install
npm run build
```
Copy `.env.example` to `.env`, fill in `HIT_BASE_URL` and `HIT_API_TOKEN`, then run:
```bash
npm start
```
The server starts on stdio. Point your MCP client at the absolute path:
```json
{
"mcpServers": {
"hit": {
"command": "node",
"args": ["/path/to/hit-mcp/dist/index.js"],
"env": {
"HIT_BASE_URL": "https://support.example.com",
"HIT_API_TOKEN": "..."
}
}
}
}
```
