mcp-mantis

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:

Variable	Required	Notes
MANTIS_REST_BASE_URL	yes	Must include index.php when URL rewriting is disabled on the host.
MANTIS_TOKEN	yes	API token from Mantis: My Account → API Tokens → Create. No username/password; the token is the Authorization header.
MANTIS_READONLY	no	false (default) enables write tools. Set true for read-only. A blank value keeps the default.
MANTIS_SEARCH_ENABLED	no	true (default) registers semantic search tools. Needs the optional @huggingface/transformers.
MANTIS_SEARCH_MODEL / MANTIS_SEARCH_DIR / MANTIS_SEARCH_THREADS	no	Embedding model, index directory, ONNX threads.
MANTIS_TIMEOUT_MS, MANTIS_METADATA_TTL_MS, MANTIS_DEFAULT_PAGE_SIZE, MANTIS_MAX_PAGE_SIZE	no	Tuning.

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

Tool	Purpose
mantis_whoami	Authenticated user + accessible projects.
mantis_list_projects / mantis_get_project	Projects with versions, categories, custom fields.
mantis_list_project_users	Project members (valid handler names for assignment).
mantis_list_issues	Paginated issues, lightweight summary by default (use mantis_get_issue for full detail). Client-side filters: status (name or "open"), assigned_to, reporter_id, date range.
mantis_get_issue / mantis_get_issues	One issue (complete) / batch fetch by ids.
mantis_get_issue_attachment	Download an attachment; images come back viewable.
mantis_get_enums / mantis_get_config	Enumerations ({id,name,label}) / raw config options.
mantis_list_filters	Stored filters (feed a filter_id into mantis_list_issues).

Resolve / write (registered when MANTIS_READONLY=false)

Tool	Purpose
mantis_update_issue	Partial update: status, resolution, handler, priority, fields… Accepts localized/canonical enum names. Optional note and dry_run.
mantis_resolve_issue	Sets both status and resolution (defaults resuelta / fixed) + optional note.
mantis_assign_issue	Assign to a handler by login name (or id), optional status change + note.
mantis_add_note	Add a public/private note.
mantis_add_relationship / mantis_remove_relationship	Link issues (related, duplicate, blocks, depends…).

Semantic search (registered when MANTIS_SEARCH_ENABLED=true)

Tool	Purpose
mantis_rebuild_search_index	Build/update the local vector index from issues (first run downloads the model).
mantis_search_issues	Natural-language search (multilingual). Optional select, highlight, date filters.
mantis_search_index_status	Index fill level and last sync.

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

Command	Purpose
npm run dev:mcp / npm run start:mcp	Run the MCP stdio server (reload / built).
npm run build	Compile TypeScript into dist/.
npm run check	Type-check, lint and format-check.
npm run dev	Express health server (GET /health, GET /health/mantis).

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.