Mantis

Node.js TypeScript MCP

An MCP stdio server that gives an AI assistant direct access to a MantisBT tracker, oriented to issue resolvers: read issues (with images), change status, resolve, assign, comment and link — plus local semantic search over issues.

REST, not SOAP. This server uses the MantisBT REST API (Mantis 2.27+), the supported and non-deprecated integration path. The legacy SOAP API is not used and does not need to be enabled.

Setup

Requires Node.js 22+ (uses the built-in global fetch).

npm install
cp .env.example .env

Then edit .env:

Register with Claude Code

From npm (published package), no local checkout needed — the token is supplied here, never stored in the repo:

claude mcp add mantis \
  -e MANTIS_REST_BASE_URL=https://mantis.example.com/api/rest/index.php \
  -e MANTIS_TOKEN=your-token-here \
  -- npx -y @grec0/mcp-mantis

Or from a local build:

npm run build
claude mcp add mantis -- node /path/to/mcp-mantis/dist/mcp.js

Equivalent .mcp.json (the env block is where MANTIS_TOKEN belongs):

{
  "mcpServers": {
    "mantis": {
      "command": "npx",
      "args": ["-y", "@grec0/mcp-mantis"],
      "env": {
        "MANTIS_REST_BASE_URL": "https://mantis.example.com/api/rest/index.php",
        "MANTIS_TOKEN": "your-token-here",
        "MANTIS_READONLY": "false"
      }
    }
  }
}

Tools

Read

Resolve / write (registered when MANTIS_READONLY=false)

Semantic search (registered when MANTIS_SEARCH_ENABLED=true)

Enum names accept the instance's localized names and the canonical English labels (e.g. asignada or confirmed). mantis_list_issues status="open" uses the live bug_resolved_status_threshold. Ad-hoc free-text search is not a server-side REST filter — use mantis_search_issues or a stored filter_id.

Commands

Project structure

src/
├── config.ts        # Validated environment configuration
├── constants.ts     # Enum aliases, relationship types
├── date-filter.ts   # Shared date-range filtering
├── mantis.ts        # MantisBT REST client (fetch, enum/handler resolution, caching)
├── tools/           # meta, issues, notes, relationships, shared helpers
├── search/          # embedder (Transformers.js), vector store, sync, search tools
├── server.ts        # Tool registration
├── mcp.ts           # MCP stdio executable
└── index.ts         # Express health endpoints

Security

.env is git-ignored (only .env.example is committed) — never commit the token. Write access is scoped to the token owner's Mantis permissions; set MANTIS_READONLY=true to disable all mutations. Health endpoints expose no credentials or user data. Run npm run check before committing.