Skip to main content
Glama

mcp-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:

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.

Related MCP server: Redmine MCP Server

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.

Available Tools

20 tools
mantis_add_noteAdd note to issueA

Adds a note (comment) to an issue. Use private=true for an internal note visible only to developers/managers. To change a field and comment in one call, use mantis_update_issue with its "note" parameter instead.

Inputs: text (required), issue_id (required), private.

mantis_add_relationshipAdd issue relationshipA

Links two issues. type is one of: related_to, duplicate_of, has_duplicate, depends_on (parent_of), blocks (child_of) — or a numeric type id.

Inputs: type (required), issue_id (required), target_id (required).

mantis_assign_issueAssign issueA

Assigns an issue to a handler (by login name or user id) and optionally changes its status in the same call. Optionally append a note.

Inputs: id (required), handler (required), note, status, +2 more.

mantis_get_configGet config optionsA
Read-onlyIdempotent

Reads arbitrary Mantis configuration options exposed to the REST API, e.g. ["status_enum_string","bug_resolved_status_threshold"].

Inputs: options (required).

mantis_get_enumsGet enumerationsA
Read-onlyIdempotent

Returns the common Mantis enumerations (status, priority, severity, resolution, reproducibility, etc.) as {id,name,label} lists. This instance is localized (Spanish names) — use it to map issue status/priority codes and to learn valid names for status changes.

Inputs: no named parameters.

mantis_get_issueGet issueA
Read-onlyIdempotent

Returns one issue by id with every field: description, steps to reproduce, notes, attachments, relationships, custom fields and history. Notes are always included.

Inputs: issue_id (required), select.

mantis_get_issue_attachmentGet issue attachmentA
Read-onlyIdempotent

Downloads an attachment of an issue. Image attachments are returned as a viewable image; other files as base64 with metadata. Find file ids in an issue's "attachments" array.

Inputs: file_id (required), issue_id (required).

mantis_get_issuesGet multiple issuesA
Read-onlyIdempotent

Fetch several issues by id in one call (max 5 concurrent). Missing/inaccessible ids return null at their position instead of failing the whole call. Includes requested/found/failed counters.

Inputs: ids (required).

mantis_get_projectGet projectA
Read-onlyIdempotent

Returns a single project by id with its versions, categories and custom fields.

Inputs: project_id (required).

mantis_list_filtersList stored filtersA
Read-onlyIdempotent

Lists stored filters, optionally scoped to a project. Pass a filter id to mantis_list_issues to run it.

Inputs: project_id.

mantis_list_issuesList issuesA
Read-onlyIdempotent

List issues (newest id first). Returns a LIGHTWEIGHT summary per issue by default (id, summary, status, handler, reporter, priority, dates…) — call mantis_get_issue for notes/attachments/history. Filter server-side by project_id / stored filter_id. The status, assigned_to, reporter_id and date filters are applied client-side (the REST API lacks them); when active, multiple pages are scanned (up to 500 issues). Use status="open" for all not-yet-resolved issues. Omit project_id to span all projects.

Inputs: page, select, status, filter_id, +8 more.

mantis_list_projectsList projectsA
Read-onlyIdempotent

Lists all projects accessible to the token owner, including nested versions, categories and custom field definitions.

Inputs: no named parameters.

mantis_list_project_usersList project membersA
Read-onlyIdempotent

Lists the members of a project (id, login name, access level). Use it to find valid handler names for assignment.

Inputs: project_id (required).

mantis_rebuild_search_indexRebuild semantic search indexA
Idempotent

Builds/updates the semantic search index from Mantis issues. Use full=true to clear and rebuild from scratch. First run downloads the embedding model (may take a minute).

Inputs: full, project_id.

mantis_remove_relationshipRemove issue relationshipA
DestructiveIdempotent

Removes a relationship from an issue by relationship id.

Inputs: issue_id (required), relationship_id (required).

mantis_resolve_issueResolve issueA

Marks an issue as resolved by setting BOTH status and resolution in one call (avoids leaving resolution as "open"). Defaults: status="resuelta", resolution="fixed" — override with names valid on this instance (see mantis_get_enums). Optionally append a note.

Inputs: id (required), note, status, dry_run, +2 more.

mantis_search_index_statusSearch index statusA
Read-onlyIdempotent

Fill level of the semantic index: indexed vs. total issues, plus last sync timestamp.

Inputs: no named parameters.

mantis_search_issuesSemantic issue searchA
Read-onlyIdempotent

Search issues by natural-language meaning (not keywords), useful to find similar/duplicate incidents. The index must be built first with mantis_rebuild_search_index. Without "select" only id+score are returned.

Inputs: query (required), top_n, select, highlight, +4 more.

mantis_update_issueUpdate issueA

Partial update of an issue (PATCH). The "fields" object accepts any of:

  • summary, description, steps_to_reproduce, additional_information (strings)

  • status, resolution, priority, severity, reproducibility: { name } (localized or canonical) or { id }

  • handler: { name: "" } or { id }

  • category, version, target_version, fixed_in_version, view_state: { name }

  • custom_fields: [{ field: {id|name}, value: "" }]

When resolving an issue set BOTH status and resolution (or use mantis_resolve_issue). Use "note" to append a comment (e.g. the reason for the change) in the same call. Use dry_run to preview the payload.

Inputs: id (required), fields (required), note, dry_run, +1 more.

mantis_whoamiWhoamiA
Read-onlyIdempotent

Returns the authenticated Mantis user (id, name, access level, accessible projects). Use it to verify the API token works.

Inputs: no named parameters.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    A4.1/5.0

    Scored across 20 tools

    Disambiguation5/5

    Each tool has a clearly distinct purpose. Even similar tools like `get_issue` vs `get_issues` and `update_issue` vs `resolve_issue` have well-defined differences explained in descriptions, so an agent can reliably choose the correct one.

    Naming Consistency5/5

    All tools start with 'mantis_' and follow a verb_noun pattern (e.g., mantis_add_note, mantis_list_issues). The only slight deviation is mantis_whoami, but that's a common convention. Overall, naming is highly consistent and predictable.

    Tool Count5/5

    20 tools cover a wide range of operations for a bug tracker: reading, updating, searching, relationships, attachments, enumerations, etc. The count is appropriate for the domain without being overwhelming.

    Completeness2/5

    The tool set lacks fundamental CRUD operations. There is no create_issue or delete_issue, and no tools to create/update/delete projects or filters. This creates significant gaps that will cause agent failures when these operations are needed.

    Related MCP Connectors

    Related MCP Servers