mcp-mantis
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@mcp-mantis list open issues assigned to me"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
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 .envThen edit .env:
Variable | Required | Notes |
| yes | Must include |
| yes | API token from Mantis: My Account → API Tokens → Create. No username/password; the token is the |
| no |
|
| no |
|
| no | Embedding model, index directory, ONNX threads. |
| 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-mantisOr from a local build:
npm run build
claude mcp add mantis -- node /path/to/mcp-mantis/dist/mcp.jsEquivalent .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 |
| Authenticated user + accessible projects. |
| Projects with versions, categories, custom fields. |
| Project members (valid handler names for assignment). |
| Paginated issues, lightweight summary by default (use |
| One issue (complete) / batch fetch by ids. |
| Download an attachment; images come back viewable. |
| Enumerations ({id,name,label}) / raw config options. |
| Stored filters (feed a |
Resolve / write (registered when MANTIS_READONLY=false)
Tool | Purpose |
| Partial update: status, resolution, handler, priority, fields… Accepts localized/canonical enum names. Optional |
| Sets both status and resolution (defaults |
| Assign to a handler by login name (or id), optional status change + note. |
| Add a public/private note. |
| Link issues (related, duplicate, blocks, depends…). |
Semantic search (registered when MANTIS_SEARCH_ENABLED=true)
Tool | Purpose |
| Build/update the local vector index from issues (first run downloads the model). |
| Natural-language search (multilingual). Optional |
| 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 |
| Run the MCP stdio server (reload / built). |
| Compile TypeScript into |
| Type-check, lint and format-check. |
| Express health server ( |
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 endpointsSecurity
.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 toolsmantis_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 optionsARead-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 enumerationsARead-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 issueARead-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 attachmentARead-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 issuesARead-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 projectARead-onlyIdempotent
Returns a single project by id with its versions, categories and custom fields.
Inputs: project_id (required).
mantis_list_filtersList stored filtersARead-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 issuesARead-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 projectsARead-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 membersARead-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 indexAIdempotent
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 relationshipADestructiveIdempotent
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 statusARead-onlyIdempotent
Fill level of the semantic index: indexed vs. total issues, plus last sync timestamp.
Inputs: no named parameters.
mantis_search_issuesSemantic issue searchARead-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_whoamiWhoamiARead-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
Scored across 20 tools
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.
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.
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.
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
Let AI agents list, read and resolve Bugsly error-tracking issues and check monitors.
Task and bug tracker for AI coding agents: 75 tools to file, triage and update work.
Manage Loom projects, tasks, bugs, defects, clients and phases from AI assistants
Manage Redbooth tasks, task lists, comments, tags and files from Claude and other AI assistants.
Related MCP Servers
- FlicenseNot gradedqualityDmaintenanceEnables interaction with MantisBT bug tracking systems through the REST API. Supports issue management, project access, user information, and note creation with type-safe operations.1-
- AlicenseNot gradedqualityDmaintenanceEnables AI assistants to interact with Redmine instances to manage issues, projects, and users. It provides comprehensive tools for issue tracking, project oversight, and user management through the Redmine REST API.MIT
- AlicenseAqualityBmaintenanceIntegrates MantisBT bug tracker into Claude and other MCP clients via the REST API. Read and manage issues, notes, file attachments, tags, relationships, and monitors — with optional offline semantic search across all issues.41825 npm12MIT
- AlicenseCqualityDmaintenanceEnables AI assistants to interact with Redmine instances, managing issues, projects, and metadata through natural language commands.1218 npmMIT