MantisBT MCP Server
MantisBT MCP server lets MCP-capable clients read and manage MantisBT data through tools.
Retrieve, filter, group, and page through issues; fetch one or many by ID with field projection.
Create, update, and delete issues; add/edit/delete notes; upload and list attachments.
Manage issue relationships, monitors/watchers, and tags.
Browse projects and project members; manage project versions (create, update, release, delete).
Inspect metadata, issue schemas/enums, configuration, current user, and server/MantisBT versions; refresh the metadata cache.
Use optional semantic search over indexed issues when enabled.
MantisBT MCP Server
English · Deutsch
A Model Context Protocol (MCP) server that integrates the MantisBT REST API into Claude Code and other MCP-capable clients. Read, create, and update issues directly from your editor.
Requirements
Node.js ≥ 22
MantisBT installation with REST API enabled (version 2.23+)
MantisBT API token (create under My Account → API Tokens)
Related MCP server: MantisBT MCP Server
Installation
Via npx (recommended):
Add to ~/.claude/claude_desktop_config.json (Claude Desktop) or your local
claude_desktop_config.json (Claude Code):
{
"mcpServers": {
"mantisbt": {
"command": "npx",
"args": ["-y", "@dpesch/mantisbt-mcp-server"],
"env": {
"MANTIS_BASE_URL": "https://your-mantis.example.com/api/rest",
"MANTIS_API_KEY": "your-api-token",
"MANTIS_UPLOAD_DIR": "/path/to/mantis-uploads"
}
}
}
}Local build:
git clone https://codeberg.org/dpesch/mantisbt-mcp-server
cd mantisbt-mcp-server
npm run init
npm run build{
"mcpServers": {
"mantisbt": {
"command": "node",
"args": ["/path/to/mantisbt-mcp-server/dist/index.js"],
"env": {
"MANTIS_BASE_URL": "https://your-mantis.example.com/api/rest",
"MANTIS_API_KEY": "your-api-token",
"MANTIS_UPLOAD_DIR": "/path/to/mantis-uploads"
}
}
}
}MANTIS_UPLOAD_DIR is optional, but recommended in stdio mode as well: it limits upload_file to files in that directory, so a prompt injection in issue text cannot make the model attach arbitrary local files. Without it, file_path can read any file the server process can read. Starting with 2.0.0, file_path will be disabled unless the variable is set. See Security considerations.
Configuration
Environment variables
Variable | Required | Default | Description |
| ✅ | – | Base URL of your MantisBT installation. Both |
| ✅ | – | API token for authentication |
| – | auto | Set to |
| – |
| Base directory for the metadata cache. Each MantisBT instance and account (base URL plus API key) gets a subdirectory of its own, named after the host plus a hash; the server logs its path on startup |
| – |
| Cache lifetime in seconds |
| – |
| Transport mode: |
| – |
| Port for HTTP mode |
| – |
| Bind address for HTTP mode. Changed from |
| ✅ (HTTP mode) | – | Bearer token for the |
| – |
| Largest accepted |
| – |
| Set to |
| – |
| Vector store backend: |
| – |
| Base directory for the search index; an explicit value also gets a subdirectory per instance and account ( |
| – |
| Embedding model name (downloaded once on first use, ~80 MB). After a change the index is rebuilt automatically on the next sync. |
| – |
| Number of ONNX intra-op threads for the embedding model. Default is 1 to prevent CPU saturation on multi-core machines and WSL. On a machine with 4 or more cores, |
| – | – | Restrict |
| – | – (all) | Comma-separated list of tool groups to offer: |
| – |
| Set to |
Limit the offered tools
Two env vars reduce the tool surface offered to the model — useful to keep the model's context shorter and to prevent accidental destructive operations:
MANTIS_TOOLSETS— include only the listed groups (comma-separated, case-insensitive)MANTIS_DISABLE_DESTRUCTIVE=true— additionally hidedelete_issue,delete_note,delete_version,remove_relationship, andremove_monitorregardless of the active groups
Hidden tools are not listed and return "Tool … not found" when called.
Group | Tools |
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
¹ hidden by MANTIS_DISABLE_DESTRUCTIVE=true · † deprecated, removed in 2.0.0 · ² additionally requires MANTIS_SEARCH_ENABLED=true; without the search group the search module is not started at all
Deprecated tools always belong to the same group as their replacement — disabling a group hides old and new name together.
Example A — triage setup (issues, notes, and metadata; no destructive operations):
{
"mcpServers": {
"mantisbt": {
"command": "npx",
"args": ["-y", "@dpesch/mantisbt-mcp-server"],
"env": {
"MANTIS_BASE_URL": "https://your-mantis.example.com/api/rest",
"MANTIS_API_KEY": "your-api-token",
"MANTIS_TOOLSETS": "issues,notes,meta",
"MANTIS_DISABLE_DESTRUCTIVE": "true"
}
}
}
}Example B — all groups, delete-protection only (36 of the 41 default tools):
{
"mcpServers": {
"mantisbt": {
"command": "npx",
"args": ["-y", "@dpesch/mantisbt-mcp-server"],
"env": {
"MANTIS_BASE_URL": "https://your-mantis.example.com/api/rest",
"MANTIS_API_KEY": "your-api-token",
"MANTIS_DISABLE_DESTRUCTIVE": "true"
}
}
}
}Available tools
Issues
Tool | Description |
| Retrieve an issue by |
| Deprecated: use |
| Filter issues by project, status, author, and more; optional |
| Create a new issue; |
| Update an existing issue; enum fields ( |
| Delete an issue |
Notes
Tool | Description |
| Deprecated: use |
| Add a note to an issue |
| Delete a note |
Attachments
Tool | Description |
| Deprecated: use |
| Upload a file to an issue — preferred: local |
Relationships
Tool | Description |
| Create a relationship between two issues; optional |
| Remove a relationship from an issue (use the |
Monitors
Tool | Description |
| Deprecated: use |
| Deprecated: use |
Tags
Tool | Description |
| List all available tags; falls back to the metadata cache when |
| Attach tags to an issue |
| Remove a tag from an issue |
Projects
Tool | Description |
| List all accessible projects; returns normalized project data (consistent with the metadata cache) |
| Get one project's master data (id, name, status, enabled, subprojects) plus, on request, its categories, users and/or versions in one call; |
| Deprecated: use |
| Create a new version in a project; returns the created version object (id, name, description, released, obsolete, timestamp); requires |
| Update an existing version; only the fields you pass are changed (at least one required); renaming rewrites version/target_version/fixed_in_version on all referencing issues; optional |
| Deprecated: use |
| Permanently delete a version — irreversible, MantisBT clears version/target_version/fixed_in_version on all referencing issues; prefer |
| Deprecated: use |
| Deprecated: use |
| Deprecated: use |
Semantic search (optional)
Semantic search understands the meaning behind a query, not just its keywords. Ask in plain language — the search engine finds conceptually related issues even when the wording doesn't match:
"login fails after password reset" — finds issues about authentication edge cases
"performance problems on the checkout page" — surfaces related reports regardless of the exact terminology used
"duplicate entries in the invoice list" — catches issues described as "shown twice", "double records", etc.
The embedding model (~80 MB) runs entirely offline — no OpenAI key, no external API. It is downloaded once on first start and cached locally. Issues are indexed incrementally on every server start (only new and updated issues are re-indexed). When several client sessions start a server at the same time, only one of them syncs the shared index. The model is loaded on first use and unloaded again after 10 minutes without embedding, so idle sessions do not hold on to its memory (~0.9 GB per server process). Long descriptions are split into up to 8 chunks so that details further down are found as well; the index then holds about 1.7 vectors per issue (around 115 MB for 7,700 issues), which every server process with search enabled keeps in memory. The ranking also takes exact keyword matches into account, so a query for an identifier, error code or version number finds the issues that contain it — and lists all issues containing such an identifier as a whole before any others, unless it occurs in more than 20 issues.
Activate with MANTIS_SEARCH_ENABLED=true.
Tool | Description |
| Natural language search over all indexed issues — combines semantic similarity with keyword matching (BM25), so exact terms such as identifiers or error codes are found as well; issues containing an identifier from the query (order number, CVE, version, code name) come first; returns top-N results with the cosine similarity as |
| Build or update the search index; |
| Deprecated: use |
Which backend to choose?
|
| |
Dependencies | None (pure JS) | Requires native build tools |
Install | Included |
|
Best for | Up to ~10,000 issues | 10,000+ issues |
Performance | Fast enough for most setups | Faster for large corpora |
Start with vectra. Switch to sqlite-vec if indexing or query times become noticeably slow.
npm install sqlite-vec better-sqlite3
# then set MANTIS_SEARCH_BACKEND=sqlite-vecMetadata & system
Tool | Description |
| Retrieve cached metadata: |
| Version of this MCP server and of the connected MantisBT installation in one response; the server part also names the commit and build time ( |
| Valid |
| Deprecated: use |
| Deprecated: use |
| Deprecated: use |
| Deprecated: use |
| List saved filters |
| Retrieve your own user profile — includes |
| Deprecated: use |
| Show server configuration (base URL, cache TTL) |
| Deprecated: use |
| Deprecated: use |
Token usage
The server handles counting and field projection itself — the model receives a compact summary instead of reading raw issue lists. Measured on 2026-10-31 against a MantisBT 2.28 installation (604 issues, five issues with long descriptions/notes):
Task | Before | Tokens | After | Tokens | Saved |
Status overview of a project (604 issues) |
| 1,274,398 |
| 165 | 99.9 % |
Open issues per handler |
| 2,686 |
| 108 | 95.9 % |
5 issues with selected fields |
| 16,272 |
| 623 | 96.1 % |
¹ list_issues scans at most 500 issues when client-side filters are active, so this "before" value is understated.
Tokens estimated as characters / 4. To reproduce against your own instance (requires a git checkout, not available via npx):
MANTIS_BASE_URL=… MANTIS_API_KEY=… \
BENCHMARK_PROJECT_ID=12 BENCHMARK_ISSUE_IDS=101,102,103,104,105 \
npm run benchmarkCredentials may also come from .env.local.
Available resources
MCP Resources are URI-addressable, read-only data that clients can fetch directly without calling a tool. They are the third MCP primitive alongside Tools and Prompts. Note that Resource support is less widely implemented in MCP clients than Tools — check your client's documentation.
Resource URI | Description |
| Profile of the authenticated API user (live fetch) |
| All accessible MantisBT projects as a compact list (cache-backed, refreshed via |
| Combined project view: project fields + users + versions + categories in one call; cache-first, list-support for enumerating all available project URIs |
| Valid values for all issue enum fields: severity, priority, status, resolution, reproducibility (live fetch) |
Available prompts
MCP prompt templates are conversation starters that instruct the LLM to collect structured input and then call the appropriate tool. They are not tools themselves — they initiate a guided workflow.
Prompt | Required args | Optional args | Description |
|
|
| Guides through a structured bug report and calls |
|
|
| Guides through a feature request and calls |
|
| – | Fetches an issue via |
|
| – | Lists issues via |
HTTP mode
For use as a standalone server (e.g. in remote setups). MCP_HTTP_TOKEN is required in HTTP mode — the server refuses to start without it:
MCP_HTTP_TOKEN=secret MANTIS_BASE_URL=... MANTIS_API_KEY=... \
TRANSPORT=http PORT=3456 node dist/index.js
# With explicit bind address (required for Docker/remote):
# MCP_HTTP_TOKEN=secret MANTIS_BASE_URL=... MANTIS_API_KEY=... \
# TRANSPORT=http PORT=3456 MCP_HTTP_HOST=0.0.0.0 node dist/index.jsEvery /mcp request must send Authorization: Bearer <token>. Over HTTP, upload_file's file_path is disabled unless MANTIS_UPLOAD_DIR is set — use the content (Base64) parameter instead. A request body may be at most 64 MB by default (MCP_HTTP_MAX_BODY_SIZE) — larger ones get 413 Payload Too Large — so content fits files up to about 48 MB.
Health check: GET http://localhost:3456/health (always public, no token required)
Security considerations
Issue descriptions, notes and attachments are written by whoever can report or comment in your MantisBT — and the model reads them. Treat them as untrusted input: a prompt injection hidden in an issue can try to make the model call write tools such as create_issue, update_issue or upload_file.
Set
MANTIS_UPLOAD_DIR— in stdio mode as well. Without it,upload_filereads any local file the server process can read viafile_path. An injected instruction could get the model to attach, for example, a private SSH key to an issue, where everyone who can read the issue sees it. WithMANTIS_UPLOAD_DIR,file_pathis limited to that directory. Over HTTP,file_pathis already disabled without it; starting with 2.0.0 the same applies to stdio.Offer only the tools you need.
MANTIS_TOOLSETSlimits the offered groups — leave outfilesif you never upload, or use onlyissues,metafor read-mostly triage.MANTIS_DISABLE_DESTRUCTIVE=truehides every delete and remove tool. Both are especially useful where people outside your team can write issues. See Limit the offered tools.Let your client confirm write calls. Every tool carries MCP annotations (
readOnlyHint,destructiveHint), so clients that support them can ask before a tool changes data.
Documentation
Cookbook — tool-oriented recipes with copy-paste-ready parameter examples for all registered tools
Usage Examples — natural language prompt examples for everyday use cases (no tool names required)
Development
npm run init # First-time setup: install deps, git hooks, typecheck
npm run build # Compile TypeScript → dist/
npm run typecheck # Type check without output
npm run dev # Watch mode for development
npm test # Run tests (vitest)
npm run test:watch # Run tests in watch mode
npm run test:coverage # Coverage report
npm run benchmark # Token benchmark against a live MantisBT (see Token usage above)
npm run benchmark:search # Search recall and exact-first order on an existing index (found like the server does: MANTIS_SEARCH_DIR, MANTIS_BASE_URL, MANTIS_API_KEY), vectors vs. hybridbenchmark:search optionally reads hand-written paraphrases (BENCHMARK_PARAPHRASES) and fixed cases with an expected ranking (BENCHMARK_EXACT); the file formats are described at the top of scripts/benchmark-search.ts.
License
MIT – see LICENSE
Feedback & Contributing
I'm always happy to hear from you — bug reports, ideas, questions, and pull requests are all welcome, on either platform:
Codeberg: issues · pull requests
GitHub: issues · pull requests
German is welcome too. Before opening a pull request, please read CONTRIBUTING.md.
If the server is useful to you, a ⭐ on Codeberg or GitHub is a great way to say thanks — and it helps others find the project.
Directories
The server is listed in these MCP directories:
Available Tools
41 toolsadd_monitorAdd Issue MonitorA
Deprecated: use update_issue with add_monitors instead — add_monitor will be removed in 2.0.0.
Add a user as a monitor (watcher) of a MantisBT issue. Monitors receive email notifications whenever the issue is updated. Returns { success, monitors } — "monitors" lists the login names now monitoring the issue.
Use it to subscribe team members to issue updates without assigning them as the handler.
Adding a user who is already a monitor is a no-op — the operation succeeds without creating duplicates.
Prerequisites: obtain issue_id from list_issues or get_issue; use get_project with member_query to look up valid MantisBT login names.
Inputs: issue_id (required), username (required).
add_noteAdd Note to IssueA
Add a note (comment) to an existing MantisBT issue. Returns the created note object including id, created_at, reporter, text, view_state, and a view_url linking directly to the note in the MantisBT web UI.
Full UTF-8 text is supported. Markdown syntax is stored as-is — rendering depends on the MantisBT instance's configured text renderer.
Use view_state="private" to restrict the note to users with reporter-level access or higher; public notes are visible to all users who can view the issue.
Prerequisites: obtain issue_id from list_issues, get_issue, or search_issues.
Inputs: text (required), issue_id (required), view_state.
add_relationshipAdd Issue RelationshipA
Add a relationship between two MantisBT issues.
Relationship types — use either type_id (numeric) or type_name (string):
0 / "duplicate_of" — this issue is a duplicate of target
1 / "related_to" — this issue is related to target
2 / "parent_of" — this issue depends on target (target must be done first); alias: "depends_on"
3 / "child_of" — this issue blocks target (target can't proceed until this is done); alias: "blocks"
4 / "has_duplicate" — this issue has target as a duplicate
Directionality note: "A child_of B" means A blocks B. "A parent_of B" means A depends on B.
Dash variants (e.g. "related-to") are also accepted for type_name.
Inputs: issue_id (required), target_id (required), type_id, type_name.
attach_tagsAttach Tags to IssueA
Attach one or more tags to a MantisBT issue.
Each tag can be specified either by ID or by name. If a tag name is provided that does not exist yet, MantisBT will create it automatically (requires tag_create_threshold permission, default: REPORTER).
Requires tag_attach_threshold permission (default: REPORTER).
Inputs: tags (required), issue_id (required).
create_issueCreate IssueA
Create a new MantisBT issue. Returns the full created issue object including the assigned id, summary, status, priority, severity, category, reporter, created_at, and view_url. With response: "short" only id, summary, project, category, status, handler, created_at and view_url (default "full"; it changes to "short" in 2.0.0).
Required fields: summary, description, project_id, category. All other fields are optional with sensible defaults (priority: "normal", severity: "minor").
Recommended workflow:
Call get_project with include: ["categories"] to obtain a valid category name
Optionally add "versions" to include to obtain version names
Optionally call get_project with member_query to resolve the assignee's username
Both priority and severity accept canonical English names or localized labels from the connected MantisBT instance — call get_issue_schema to see all available values.
For the handler, prefer the username field (resolved server-side) over handler_id when working interactively.
Inputs: summary (required), category (required), project_id (required), description (required), +13 more.
create_versionCreate VersionA
Create a new version in a MantisBT project. Returns the created version object (id, name, description, released, obsolete, timestamp).
Version names must be unique within the project. Without timestamp, MantisBT uses the current date.
Requires the manage_project_threshold access level in the project (MantisBT default: manager).
Inputs: name (required), project_id (required), obsolete, released, +2 more.
delete_issueDelete IssueBDestructiveIdempotent
Permanently delete a MantisBT issue. This action is irreversible.
Inputs: id (required).
delete_noteDelete NoteADestructiveIdempotent
Permanently delete a note from a MantisBT issue. This action is irreversible — deleted notes cannot be recovered.
Returns a plain-text confirmation message on success. Returns an error if the note does not exist or the current user lacks permission to delete it (MantisBT enforces access control: users can typically only delete their own notes unless they have manager-level access or higher).
Prerequisites: obtain note_id from get_issue (notes[].id).
Inputs: note_id (required), issue_id (required).
delete_versionDelete VersionADestructiveIdempotent
Permanently delete a version of a MantisBT project. This action is irreversible.
MantisBT clears the version, target_version and fixed_in_version fields of all issues that reference the deleted version (including subprojects if versions are inherited). To retire a version without touching issues, set obsolete=true via update_version instead.
The version must belong to project_id itself: versions inherited from a parent project can only be changed via the parent's project_id (otherwise MantisBT answers "Version not found"). get_project with include: ["versions"] and without inherit lists the project's own versions.
Requires the manage_project_threshold access level in the project (MantisBT default: manager).
Inputs: project_id (required), version_id (required).
detach_tagDetach Tag from IssueAIdempotent
Remove a tag from a MantisBT issue.
Requires tag_detach_own_threshold (default: REPORTER) for own tags, or tag_detach_threshold (default: DEVELOPER) for tags attached by others.
Inputs: tag_id (required), issue_id (required).
find_project_memberFind Project MemberARead-onlyIdempotent
Deprecated: use get_project with member_query instead — find_project_member will be removed in 2.0.0.
Search for users with access to a MantisBT project by name, display name, or email.
Returns up to limit matching users (default: 10, max: 100). Matching is case-insensitive substring search across name, real_name, and email fields. Omit query to list the first limit users.
Data is served from the local metadata cache when fresh; falls back to a live API call otherwise.
Inputs: project_id (required), limit, query.
get_configGet MantisBT ConfigurationARead-onlyIdempotent
Retrieve one or more MantisBT configuration options.
Common option names:
"status_enum_string" — issue status values and their IDs
"priority_enum_string" — priority values
"severity_enum_string" — severity values
"resolution_enum_string" — resolution values
"reproducibility_enum_string" — reproducibility values
"view_state_enum_string" — view state values
"access_levels_enum_string" — access level values
Inputs: options (required).
get_current_userGet Current UserARead-onlyIdempotent
Retrieve the profile of the user associated with the current API key: id, name (login name), real_name, email, language, timezone, access_level, created_at and the accessible projects.
"language" is the MantisBT language of this user (e.g. "german", "english") — use it as the hint for which language to write issue texts and notes in, and expect localized enum labels in that language.
Inputs: no named parameters.
get_issueGet IssueARead-onlyIdempotent
Retrieve one MantisBT issue by "id", or several by "ids" (1–50). Pass exactly one of the two.
With "id": returns the issue with all fields including notes (each with view_url), attachments and relationships, unless "select" is given. With "ids": returns { issues, requested, found, failed } — requests run in parallel (max 5 concurrent); missing or inaccessible IDs give null at their position instead of failing the call.
Use "select" to fetch only some fields, e.g. select: "notes" for just the notes or select: "attachments" for just the file attachments of an issue.
Inputs: id, ids, select.
get_issue_enumsGet Issue Enum ValuesARead-onlyIdempotent
Deprecated: use get_issue_schema instead — get_issue_enums will be removed in 2.0.0.
Return valid ID, name, and (if available) localized label for all issue enum fields.
Use this tool before creating or updating issues to look up the correct value for severity, status, priority, resolution, or reproducibility.
Example response (English installation): { "severity": [{"id": 10, "name": "feature"}, {"id": 50, "name": "minor"}, ...], "status": [{"id": 10, "name": "new"}, {"id": 20, "name": "feedback"}, ...], "priority": [{"id": 10, "name": "none"}, {"id": 30, "name": "normal"}, ...], "resolution": [{"id": 10, "name": "open"}, {"id": 20, "name": "fixed"}, ...], "reproducibility": [{"id": 10, "name": "always"}, {"id": 70, "name": "have not tried"}, ...] }
Example response (localized installation, e.g. German): { "status": [ {"id": 10, "name": "new", "label": "Neu"}, {"id": 20, "name": "feedback", "label": "Feedback"}, {"id": 30, "name": "acknowledged", "label": "Bestätigt"}, ... ], ... }
Fields:
"id" — numeric ID accepted by the API
"name" — localized or canonical name from the MantisBT database
"label" — UI display label (only present when it differs from "name")
"canonical_name" — English canonical name (only present on localized installs)
For create_issue (severity, priority, reproducibility): pass the canonical English name, the localized "name", or the "label" — all are accepted. The server resolves them to the correct ID.
For update_issue: pass either "id" or "name" in the field reference object.
Note: on some installations enum values are customized at the database level. In that case "name" itself may be localized (e.g. "kleinerer Fehler" instead of "minor") and no "label" will be present because there is no separate English original.
Inputs: no named parameters.
get_issue_fieldsGet Issue FieldsARead-onlyIdempotent
Deprecated: use get_issue_schema instead — get_issue_fields will be removed in 2.0.0.
Return all field names that are valid for the "select" parameter of list_issues and get_issue.
Fields are discovered by fetching a sample issue from MantisBT (which reflects the server's active configuration — e.g. whether eta, projection, or profile fields are enabled) and merging the result with fields that MantisBT omits when empty (notes, attachments, relationships, etc.). The result is cached with the same TTL as the metadata cache.
Use this tool before constructing a "select" string to ensure you only request fields that exist on this server.
Inputs: project_id.
get_issuesGet Multiple IssuesARead-onlyIdempotent
Deprecated: use get_issue with ids instead — get_issues will be removed in 2.0.0.
Retrieve multiple MantisBT issues by their numeric IDs in a single MCP call. Requests run in parallel (max 5 concurrent). Missing or inaccessible IDs return null at their array position — the call never fails due to individual missing IDs. Response includes "requested", "found", and "failed" counters for quick validation.
Inputs: ids (required).
get_issue_schemaGet Issue SchemaARead-onlyIdempotent
Return what is valid for issues on this MantisBT server, in one response:
fields: all field names valid for the "select" parameter of get_issue, list_issues and search_issues. Discovered from a sample issue (reflects the server's active configuration) plus fields MantisBT omits when empty (notes, attachments, relationships, …); cached with the metadata TTL. fields_source tells where they came from: "cache", "live" or "static".
enums: ID, name and (if available) localized label for severity, status, priority, resolution and reproducibility. "name" or "id" is what create_issue / update_issue accept; "canonical_name" appears on localized installations.
Call it before building a "select" string or before setting enum fields.
Inputs: project_id.
get_mantis_versionGet MantisBT VersionARead-onlyIdempotent
Deprecated: use get_version instead — get_mantis_version will be removed in 2.0.0.
Returns the version of the connected MantisBT installation and optionally compares it against the latest official release on GitHub.
Inputs: check_latest.
get_mcp_versionGet MCP Server VersionARead-onlyIdempotent
Deprecated: use get_version instead — get_mcp_version will be removed in 2.0.0.
Returns the version of this mantisbt-mcp-server instance.
Inputs: no named parameters.
get_metadataGet Cached MetadataARead-onlyIdempotent
Return the cached MantisBT metadata (projects with their users, versions and categories, plus all tags).
detail: "summary" (default) — compact counts: project count, tag count, per-project counts of users, versions and categories, cached_at, ttl_seconds.
detail: "full" — the complete raw cache with all lists (large; minified JSON).
refresh: true — re-fetch everything from MantisBT before answering (otherwise the cache is used and only synced when missing or expired; default TTL 24 hours).
When semantic search is enabled, the response also contains "search_index": how many issues are indexed vs. the total, and the time of the last sync.
For lists of a single project use get_project with include; for tags use list_tags.
Inputs: detail, refresh.
get_metadata_fullGet Full Cached MetadataARead-onlyIdempotent
Deprecated: use get_metadata with detail: "full" instead — get_metadata_full will be removed in 2.0.0.
Return the complete raw MantisBT metadata cache: all projects with full fields, and per-project lists of users, versions, categories, plus all tags.
If the cache does not exist or has expired (default TTL: 24 hours), it will automatically sync first. Use get_metadata with refresh: true to force a refresh.
Inputs: no named parameters.
get_projectGet ProjectARead-onlyIdempotent
Get one MantisBT project: its master data (id, name, description, status, enabled, view_state, access_level, subprojects as id and name of the direct subprojects) and, on request, its categories, users and versions in the same call.
include: any of "categories", "users", "versions" (default: none — master data only).
categories: names come without the "[All Projects] " prefix, ready for create_issue / update_issue.
users: id, name (login name), real_name, email, access_level. access_level returns only users at or above that level (10=viewer, 25=reporter, 40=updater, 55=developer, 70=manager, 90=administrator) and implies include "users".
member_query: case-insensitive substring search in login name, real name and email; returns all matching users. Implies include "users".
versions: id, name, released, obsolete, timestamp. obsolete=true adds obsolete versions, inherit=true adds versions of parent projects; either implies include "versions".
Users come from the local metadata cache when it is fresh and no access_level is given. Prerequisites: obtain project_id from list_projects.
Inputs: project_id (required), include, inherit, obsolete, +2 more.
get_project_categoriesGet Project CategoriesARead-onlyIdempotent
Deprecated: use get_project with include: ["categories"] instead — get_project_categories will be removed in 2.0.0.
List all categories available for a MantisBT project.
Note: The MantisBT API returns global (cross-project) categories with a "[All Projects] " prefix. This tool strips that prefix so the returned names can be used directly when creating issues.
Inputs: project_id (required).
get_project_usersGet Project UsersARead-onlyIdempotent
Deprecated: use get_project with include: ["users"] instead — get_project_users will be removed in 2.0.0.
List all users with access to a specific MantisBT project. Returns an array of user objects, each containing id, name (login name), real_name, email, and access_level fields.
Access level IDs: 10=viewer, 25=reporter, 40=updater, 55=developer, 70=manager, 90=administrator.
Prerequisites: obtain project_id from list_projects.
Inputs: project_id (required), access_level.
get_project_versionsGet Project VersionsARead-onlyIdempotent
Deprecated: use get_project with include: ["versions"] instead — get_project_versions will be removed in 2.0.0.
List all versions defined for a MantisBT project. Returns an array of version objects, each containing id, name, released (boolean), obsolete (boolean), and timestamp (version date). To create, change, release or delete versions use create_version, update_version, release_version and delete_version.
Use the returned version names directly when creating or updating issues via create_issue and update_issue (version, target_version, fixed_in_version fields).
By default, obsolete and inherited parent-project versions are excluded. Set obsolete=true to include deprecated versions; set inherit=true to also return versions from parent projects.
Prerequisites: obtain project_id from list_projects.
Inputs: project_id (required), inherit, obsolete.
get_versionGet VersionsARead-onlyIdempotent
Return the version of this mantisbt-mcp-server and of the connected MantisBT installation in one response: { mcp_server: { version, commit?, built_at? }, mantis: { installed_version, latest_version?, status?, github_note? } }
mcp_server describes the running build: version ends in "-dev" unless it is a published release; commit is the short hash it was built from ("-dirty" with uncommitted changes), built_at the ISO-8601 build time.
The MantisBT version is read from the X-Mantis-Version response header. With check_latest (default: true) it is compared against the latest MantisBT release on GitHub (outbound HTTPS request, up to 5 seconds); status is "up-to-date", "update-available", "newer-than-release" or "unknown". If MantisBT cannot be reached, mantis contains "error" instead and mcp_server is still returned.
Inputs: check_latest.
list_filtersList Saved FiltersARead-onlyIdempotent
List all saved MantisBT issue filters accessible to the current user. Filter IDs can be used with list_issues.
Inputs: no named parameters.
list_issue_filesList Issue File AttachmentsARead-onlyIdempotent
Deprecated: use get_issue with select: "attachments" instead — list_issue_files will be removed in 2.0.0.
List all file attachments of a MantisBT issue. Returns an array of attachment objects, each containing id, filename, size in bytes, content_type, and download_url. Returns an empty array if the issue has no attachments.
Inputs: issue_id (required).
list_issuesList IssuesARead-onlyIdempotent
List MantisBT issues with optional filtering. Returns a paginated list of issues. Use the "select" parameter to limit returned fields and reduce response size significantly.
Note: "assigned_to", "reporter_id", "status", and date filters are applied client-side (the MantisBT REST API does not support these as server-side filters). When any of these filters are active the tool automatically fetches multiple pages internally until enough matching results are found (up to 500 issues scanned); if that limit ends the search before the page is full, the response contains "truncated": true. The "page" and "page_size" parameters refer to the resulting filtered list.
Tip for date queries: fetching with select="id,updated_at,created_at" plus a date filter is very compact and efficient.
For overviews use "group_by" ("status", "handler", "priority" or "category"): the server counts all matching issues itself and returns { group_by, total, groups: [{ id, name, label?, count }] } instead of an issue list — far fewer tokens than listing issues and counting them. All filters still apply. If the scan stops at its limit (50,000 issues), the response contains "truncated": true.
Inputs: page, sort, select, status, +11 more.
list_languagesList Supported LanguagesARead-onlyIdempotent
Deprecated: use get_current_user (field "language") instead — list_languages will be removed in 2.0.0.
Despite its name, MantisBT's GET /lang returns only the language of the current user ({ strings, language }), not a list of all languages.
Inputs: no named parameters.
list_notesList Issue NotesARead-onlyIdempotent
Deprecated: use get_issue with select: "notes" instead — list_notes will be removed in 2.0.0.
List all notes (comments) attached to a MantisBT issue.
Inputs: issue_id (required).
list_projectsList ProjectsARead-onlyIdempotent
List all MantisBT projects accessible to the current API user.
Inputs: no named parameters.
list_tagsList TagsARead-onlyIdempotent
List all tags defined in the MantisBT installation.
The MantisBT REST API exposes a GET /tags endpoint on some installations. If that endpoint is not available, this tool falls back to the local metadata cache populated by get_metadata.
Inputs: page, page_size.
release_versionRelease VersionA
Deprecated: use update_version with released=true, timestamp and (optionally) next_version instead — release_version will be removed in 2.0.0.
Mark a version as released and set its date (default: now). Optionally create a follow-up version in the same step.
The follow-up version is only created when next_version is given; its name is used as-is — no automatic numbering.
Returns { released: } plus either next_version: or next_version_error: . The two steps are separate API calls: if creating the follow-up version fails, the release itself stays in effect and the error is reported in next_version_error.
The version must belong to project_id itself: versions inherited from a parent project can only be changed via the parent's project_id (otherwise MantisBT answers "Version not found"). get_project with include: ["versions"] and without inherit lists the project's own versions.
Requires the manage_project_threshold access level in the project (MantisBT default: manager).
Inputs: project_id (required), version_id (required), timestamp, next_version.
remove_monitorRemove Issue MonitorADestructiveIdempotent
Deprecated: use update_issue with remove_monitors instead — remove_monitor will be removed in 2.0.0.
Remove a user from the monitor list of a MantisBT issue. The user will no longer receive email notifications for updates to this issue.
Returns { success, removed, monitors } — "monitors" lists the login names still monitoring the issue. If the user was not a monitor, the call succeeds with removed=false and nothing is changed.
Removing another user requires the monitor_delete_others_bug_threshold access level; without it the call returns an error.
Inputs: issue_id (required), username (required).
remove_relationshipRemove Issue RelationshipADestructive
Remove a relationship from a MantisBT issue.
Use get_issue first to retrieve the relationship IDs. The relationship_id is the numeric id field of a relationship object in the issue's relationships array (not the type ID).
Inputs: issue_id (required), relationship_id (required).
sync_metadataSync Metadata CacheA
Deprecated: use get_metadata with refresh: true instead — sync_metadata will be removed in 2.0.0.
Fetch all projects and their associated users, versions, categories, and tags from MantisBT and store them in the local metadata cache.
Tags are fetched via the dedicated GET /tags endpoint when available. On installations where that endpoint is missing (MantisBT < 2.26), tags are collected by scanning all issues across all projects.
This is useful for getting a complete overview of your MantisBT installation. The cache is valid for 24 hours by default (configurable via MANTIS_CACHE_TTL env var). Use this tool to refresh stale data.
Inputs: no named parameters.
update_issueUpdate IssueA
Update one or more fields of an existing MantisBT issue using a partial PATCH.
The "fields" object accepts any combination of:
summary (string)
description (string)
steps_to_reproduce (string)
additional_information (string)
status: { name: "new"|"feedback"|"acknowledged"|"confirmed"|"assigned"|"resolved"|"closed" }
resolution: { id: 20 } (20 = fixed/resolved)
handler: { id: <user_id> } or { name: "" }
priority: { name: "<priority_name>" }
severity: { name: "<severity_name>" }
reproducibility: { name: "<reproducibility_name>" }
category: { name: "<category_name>" }
version: { name: "<version_name>" } (affected version)
target_version: { name: "<version_name>" }
fixed_in_version: { name: "<version_name>" }
view_state: { name: "public"|"private" }
custom_fields: [{field: {id|name}, value: ""}] (only the listed custom fields are changed, others stay untouched; use get_issue_schema to discover fields)
notes: [{ id: <note_id>, text?: "", view_state?: "public"|"private" }] (edits existing notes; note IDs come from get_issue. An omitted view_state keeps the note's current visibility. To add a new note use the "note" parameter or add_note.)
Important: when resolving an issue, always set BOTH status and resolution to avoid leaving resolution as "open".
Use the optional "note" parameter to append a note in the same call (e.g. the reason for a status change) — no separate add_note call needed. For a note without field changes use add_note.
Use "add_monitors" / "remove_monitors" (lists of MantisBT login names) to change who watches the issue — "fields" may be omitted then. The response contains "monitors" with added/removed/not_monitoring and the current monitor list. Adding or removing other users requires the monitor_add_others_bug_threshold / monitor_delete_others_bug_threshold access level.
The response is the updated issue. With response: "short" it holds only id, summary, status, resolution, updated_at, view_url and the fields that were changed (custom_fields and notes narrowed to the changed entries; an appended note as { id, view_url }) — use it for routine changes. Default is "full"; it changes to "short" in 2.0.0.
Steps run in order: fields, monitors, note. Once one step succeeded, a later failure is reported inline ("notes_error" when a note edit was not applied, "monitors_error", "note_error") instead of failing the call — do not retry the steps that went through. Only if every requested step failed is the call an error.
Inputs: id (required), note, fields, dry_run, +4 more.
update_versionUpdate VersionAIdempotent
Update an existing version of a MantisBT project. Only the fields you pass are changed. Returns the updated version object.
Renaming a version also rewrites the version, target_version and fixed_in_version fields of all issues that reference it (including subprojects if versions are inherited).
Setting released=true does not change the version date — pass timestamp as well (e.g. the release date).
To release a version: released=true, timestamp=, and optionally next_version= to create the follow-up version in the same call. With next_version the response is { version: , next_version: } — or next_version_error: if creating the follow-up failed (the update itself stays in effect). Without next_version the response is the updated version object.
The version must belong to project_id itself: versions inherited from a parent project can only be changed via the parent's project_id (otherwise MantisBT answers "Version not found"). get_project with include: ["versions"] and without inherit lists the project's own versions.
Requires the manage_project_threshold access level in the project (MantisBT default: manager).
Inputs: project_id (required), version_id (required), name, obsolete, +4 more.
upload_fileUpload File AttachmentA
Upload a file as an attachment to a MantisBT issue. Adds the file to the issue without modifying any issue fields or status. Returns the created attachment metadata on success.
Provide exactly one of the two input modes:
file_path (preferred): absolute path to a local file — use this whenever the file exists on disk; the server reads and encodes it automatically; filename is derived from the path. Note: file_path reads from the server's filesystem and is disabled over the HTTP transport unless MANTIS_UPLOAD_DIR is configured — HTTP clients should use content instead.
content: Base64-encoded file content — only use this when the file is not accessible via a path (e.g. in-memory data); filename must be supplied explicitly via the filename parameter
The optional content_type sets the MIME type (e.g. "image/png"); defaults to "application/octet-stream". Use the optional description to annotate the attachment.
Use this tool to attach files such as logs, screenshots, or patches to an existing issue. To list existing attachments, use get_issue with select: "attachments".
Inputs: issue_id (required), content, filename, file_path, +2 more.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 41 tools
Roughly 17 of the 41 tools are deprecated aliases whose functionality is fully absorbed by consolidated tools (get_issue vs get_issues, get_project vs get_project_users/get_project_versions/get_project_categories, get_metadata vs get_metadata_full/sync_metadata, get_version vs get_mcp_version/get_mantis_version, update_issue vs add_monitor/remove_monitor/release_version). Descriptions reference a search_issues tool that does not exist in the set, and list_notes/list_issue_files/get_issue_fields overlap with get_issue(select) and get_issue_schema. An agent must read deprecation notes on nearly every second tool to pick correctly.
The dominant convention is snake_case verb_noun, which is followed by most tools. However there are visible breaks: attach_tags (plural) vs detach_tag (singular), get_issue vs the deprecated get_issues, and get_mcp_version/get_mantis_version which do not match the get_version naming being promoted. Mixed deprecated/current pairs make the surface read as two generations of naming.
41 tools is far past the comfortable range for a single MCP server, and a large fraction of them exist only as back-compat shims. The remaining ~24 live tools still exceed a clean scope because get_project, get_metadata and get_issue have been overloaded with include/detail/select parameters rather than split cleanly.
Core issue lifecycle is well covered: create/get/list/update/delete issues, notes, attachments, relationships, monitors, tags, projects and versions, plus schema/enum and config discovery. Remaining gaps are modest: no project create/update, no dedicated tag create/update/delete (attach_tags implicitly creates), and no note-edit tool other than via update_issue.
Maintenance
Related MCP Connectors
MCP-native notes and memory for ChatGPT, Claude, and other AI tools.
Manage Redbooth tasks, task lists, comments, tags and files from Claude and other AI assistants.
Private persistent memory for Claude, ChatGPT & Gemini via MCP - semantic search, zero-code setup.
Persistent memory for AI assistants. Save once; recall from Claude, ChatGPT, or any MCP client.
Related MCP Servers
- AlicenseBqualityDmaintenanceA Model Context Protocol (MCP) service that enables integration with Mantis Bug Tracker, allowing users to query and analyze bug tracking data through natural language commands.827 npm12MIT
- 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-
- AlicenseAqualityDmaintenanceConnect Claude to your Redmine instance to search, browse, create and update issues, manage time entries, and upload/download attachments.51Mozilla Public 2.0
- AlicenseAqualityCmaintenanceProvides AI assistants with direct access to MantisBT issue trackers via the REST API, enabling reading, updating, resolving, and semantically searching issues.2015 npmMIT