MantisBT MCP Server
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., "@MantisBT MCP Server summarize my unresolved assigned bugs by project and priority"
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.
MantisBT MCP Server
A Model Context Protocol (MCP) server that connects AI assistants to MantisBT, the open-source bug tracker. It exposes 25 tools covering the MantisBT REST API, a context-aggregation tool for an assignee's open work, and a local vector store that powers semantic search and engineering efficiency analytics.
Features
Full REST coverage. Issues, notes, time tracking, relationships, tags, attachments, monitoring, projects, versions, filters, users, and server configuration.
LLM-ready context.
get_my_unresolved_assigned_contextgathers every unresolved issue assigned to a user, including notes, history, and custom fields, and summarizes them by project, priority, and status. Binary attachments are excluded and can be downloaded on demand.Works around API limits. MantisBT's REST API cannot filter by assignee and status together. The server combines native filters with a bounded paginated scan and client-side filtering.
Deployment-friendly URLs. Accepts the site root,
/api/rest, or/api/rest/index.php, and falls back automatically on servers withoutmod_rewrite.Local semantic search. Issues are embedded into 256-dimension vectors on your machine (no model download, no network), stored in one JSON file, and searched by cosine similarity. An OpenAI-compatible embedding endpoint can be used instead.
Engineering efficiency analytics. Computes throughput, lead time (mean, P50, P90), reopen rate, assignment ping-pong, stagnant and overdue work, per-assignee breakdown, recurring semantic clusters of problems, and a deterministic 0–100 efficiency score with diagnostics.
Related MCP server: Redmine MCP Server
About the vector store (optional)
The vector store is a local index of your MantisBT issues. Every other tool works without it.
What it is for
Semantic search (
search_vector_issues): describe a problem and get the most similar issues by cosine similarity. Useful for finding duplicates and earlier bugs with the same cause, without scanning the API on every question.Recurring-problem clusters (
analyze_project_efficiency): groups similar issues, such as several "payment timeout" reports, to show where the team repeats work. The same report adds throughput, lead time (mean, P50, P90), reopen rate, assignment ping-pong, stagnant and overdue work, and a 0-100 score. Most of those metrics are plain calculations on MantisBT data; only the clustering and search use similarity.Offline and fast: vectors live in one local JSON file, with no model download and no network. Fill it with
sync_issues_to_vector_store.
Limits
The default embedder hashes words and character trigrams. It matches shared words and patterns, not meaning, so "slow" and "lag" may not match. An OpenAI-compatible embedding endpoint can replace it, at the cost of sending issue text to a third party.
The file is loaded fully into memory. It suits thousands of issues, not millions.
It contains issue text, so treat it as confidential. It is git-ignored and written with owner-only permissions.
Changing the embedding mode requires running
sync_issues_to_vector_storeagain.
Requirements
Node.js 18 or later (uses the global
fetch)A MantisBT instance with the REST API enabled
A MantisBT API token for an account with the permissions you need
Quick Start
git clone <repository-url> Mantis-MCP
cd Mantis-MCP
npm install
npm run build
npm testCreate a .env file from the template:
cp .env.example .envThen set MANTIS_BASE_URL and MANTIS_API_TOKEN. Connect the server to your MCP client:
{
"mcpServers": {
"mantisbt": {
"command": "node",
"args": ["/absolute/path/to/Mantis-MCP/dist/index.js"],
"env": {
"MANTIS_BASE_URL": "https://mantis.example.com",
"MANTIS_API_TOKEN": "your_token_here"
}
}
}
}Restart the client and run check_mantis_connection to confirm the setup.
Installation Tutorial for Agents
This section is written for an AI agent (for example, a coding assistant) that installs the server on behalf of a user. Run each step in order. After each step, check the stated expected result before continuing. If a check fails, stop and report the output to the user. Do not skip steps or invent values.
Step 1: Check prerequisites
Run:
node -v
npm -vExpected: Node.js major version 18 or higher. npm is installed with Node.js.
If Node.js is missing or older than 18, stop and ask the user to install Node.js 18 or later. Do not install it silently.
Step 2: Get the code
If the repository is not already on disk:
git clone <repository-url> Mantis-MCP
cd Mantis-MCPIf it is already on disk, change into its directory. The directory must contain package.json and src/.
Step 3: Install dependencies
npm installExpected: the command exits with code 0. Dependencies are @modelcontextprotocol/sdk and zod. Development dependencies are typescript and @types/node.
Step 4: Build
npm run buildExpected: the command exits with code 0 and creates dist/index.js. Verify the file exists before continuing.
Step 5: Run the tests
npm testExpected output includes # pass 4 and # fail 0. The tests do not contact MantisBT, so they pass without credentials. If any test fails, stop and report the failing test name and its output.
Step 6: Create the configuration file
Copy the template:
cp .env.example .envOn Windows PowerShell, use Copy-Item .env.example .env.
Then ask the user for two values. Do not invent them:
Variable | What to ask the user for |
| The MantisBT site URL, for example |
| An API token created in MantisBT under the user's account settings. |
Edit .env and replace the two placeholder values. Leave the other variables at their defaults unless the user asks for a change. Never print the token in chat output, and never commit .env.
Step 7: Register the server in the MCP client
Use the client's own MCP configuration. The entry must start the compiled server with Node.js. Use an absolute path to dist/index.js:
{
"mcpServers": {
"mantisbt": {
"command": "node",
"args": ["<absolute-path-to-repo>/dist/index.js"],
"env": {
"MANTIS_BASE_URL": "<value from .env>",
"MANTIS_API_TOKEN": "<value from .env>"
}
}
}
}Replace <absolute-path-to-repo> with the full path to the repository on this machine. Replace the two <value from .env> placeholders with the actual values. Where the client accepts it, the env block can be omitted if the server reads .env from the repository root (not from the working directory). The server does this automatically.
Where the config file lives depends on the client. Look up the client's documentation for MCP server configuration instead of guessing a path. Save the change, then restart or reload the client so it starts the server.
Step 8: Verify the connection
From the MCP client, call the tool check_mantis_connection with no arguments.
Expected: the result reports a successful connection and the authenticated user. If the result has isError: true, use the troubleshooting table below. Report the error text to the user.
Then call get_current_user. Expected: the profile of the token's user. This confirms the token works for user-specific endpoints.
Step 9 (optional): Build the vector index
Only do this if the user wants semantic search or efficiency analytics:
Call
sync_issues_to_vector_storewithmax_pages: 2to test on a small set.If that succeeds, the index can be grown with larger
max_pagesvalues.
The index is written to .mantis-vector-store.json in the repository directory, or to the path in MANTIS_VECTOR_DB_PATH.
Troubleshooting
Symptom | Check | Fix |
| Node.js and npm versions, network access | Upgrade Node.js to 18 or later. Retry. |
| Output of | Report the TypeScript error. Do not edit source files to make it pass without the user's approval. |
|
| Fix the values in |
| Token value | Ask the user to create a new token in MantisBT and update it. |
|
| The server already tries |
Client shows no tools | Path in client config is absolute and correct; client was restarted | Fix the path, then restart the client. |
|
| Put the full path to the |
Installation checklist
Node.js 18 or later is installed
npm installexits with code 0npm run buildexits with code 0 anddist/index.jsexistsnpm testreports 4 passing tests.envexists with realMANTIS_BASE_URLandMANTIS_API_TOKENThe MCP client config points to the absolute path of
dist/index.jsThe client was restarted
check_mantis_connectionsucceeds
Tools at a Glance
Group | Tools |
Context for LLMs |
|
Vector store and analytics |
|
Issues |
|
Notes and time tracking |
|
Relationships, tags, attachments, monitoring |
|
Projects, versions, filters, users, settings |
|
Parameters and examples for every tool are in docs/TOOLS.md.
Tutorial for LLMs
This section is written for the AI assistant that calls these tools. Follow it to pick the right tool, call it with valid arguments, and report results accurately.
1. Ground rules
Check the connection first when a call fails or when you are unsure the server is configured. Call
check_mantis_connection. If it returns an error, report the error text to the user. Do not guess a fix.Use IDs, not names, in write calls.
issue_id,project_id,handler_id, anduser_idare integers. Look them up withlist_projects,get_current_user, orlist_issuesfirst.Prefer the narrowest tool. Use
get_issue_full_contextfor one issue, notlist_issuesfollowed by many reads.Keep payloads small. Download attachments only when the content is needed, with
get_issue_attachment.Treat errors as data. A result with
isError: truecontains{"error": "..."}. Quote the message to the user and stop that branch. Do not retry the same call unchanged.Confirm before destructive actions.
delete_issueanddelete_issue_notecannot be undone. Ask the user first unless they clearly asked for the deletion.
2. Choose a tool by intent
The user asks for... | Call |
"What do I have to work on?" |
|
"What's going on with issue #42?" |
|
"Show open bugs in project 3" |
|
"Have we seen this problem before?" |
|
"How healthy is project 3?" |
|
"Open a bug for X" |
|
"Mark #42 as in progress for Ana" |
|
"Log 1h30 on #42" |
|
"Is #42 a duplicate of #17?" |
|
3. Workflows
A. Daily triage of my work
Call
get_my_unresolved_assigned_context. Use the executive summary for an overview.For the top items, call
get_issue_full_contextwith eachissue_idto read the description and notes.Report the list grouped by priority. Do not invent details missing from the result.
{ "name": "get_my_unresolved_assigned_context", "arguments": { "project_id": 3, "max_pages": 5 } }B. Investigate a bug
get_issue_full_contextwithissue_id.search_vector_issueswithqueryset to the issue summary, andonly_unresolved: falseto find past solutions. Results need a priorsync_issues_to_vector_store. If the store is empty, the result contains an explanatory message.Report the closest matches with their
idand similarity score. Say that the match is semantic, not proof of a duplicate.
{ "name": "search_vector_issues", "arguments": { "query": "timeout in PIX payment webhook", "top_k": 5, "min_similarity": 0.1 } }C. Build the vector index
sync_issues_to_vector_storewithproject_idandmax_pages. Start small (max_pages: 2) to check the result.Report what the result says about the sync. Re-run after large changes in MantisBT.
{ "name": "sync_issues_to_vector_store", "arguments": { "project_id": 3, "max_pages": 5 } }D. Project efficiency review
analyze_project_efficiencywithproject_id. Leaveauto_syncattrueunless the user says not to sync.Report the Efficiency Score, the throughput and lead time figures, and the
diagnosticslist in that order.Use
top_stale_unresolved_issuesandassignee_efficiencyto suggest concrete next steps. Do not change any issue without the user's approval.
{ "name": "analyze_project_efficiency", "arguments": { "project_id": 3, "stale_threshold_hours": 168 } }E. Create and update an issue
Confirm the
project_idandcategory_namewithlist_projects, which returns categories.create_issuewith a clearsummaryand a fulldescription. Includesteps_to_reproducewhen the user provides them.Use the returned
idin later calls. Useupdate_issueonly for fields the user asked to change.
{ "name": "create_issue", "arguments": { "project_id": 3, "category_name": "Bug", "summary": "Checkout fails with 504 on PIX QR code", "description": "Observed on staging after the last deploy.", "priority_name": "high" } }F. Log work and comment
add_issue_notewithtext,view_state(publicunless the user says private), andtime_tracking_durationinHH:MMformat when the user gives hours.Report the result to the user and quote any ID it returns.
{ "name": "add_issue_note", "arguments": { "issue_id": 42, "text": "Root cause found in the connection pool.", "view_state": "public", "time_tracking_duration": "01:30" } }G. Read an attachment
get_issue_full_contextlists attachment metadata (id,filename,size_bytes,content_type).Call
get_issue_attachmentwithissue_idandattachment_idonly if the content is needed. Do not download binary files just to describe them.
4. Reporting results
Lead with the answer, then the supporting figures.
Quote issue IDs and summaries exactly as returned.
Mark anything inferred, such as a semantic match or a suggested next step, as an inference.
If a call fails, say which tool failed, the error message, and what the user can check (URL, token, permissions, IDs).
5. Common errors
Error text contains | Likely cause | What to tell the user |
| Configuration missing | Add both variables to the MCP client |
| Token invalid or expired | Create a new API token in MantisBT. |
| Account lacks permission | The token's account cannot perform this action. |
| Wrong ID, or REST path issue | Verify the ID with |
| ID does not exist | Ask the user to confirm the ID. |
"No issues found in the vector store" | Index is empty | Run |
Configuration
Variable | Required | Default |
| Yes | none |
| Yes | none |
| No |
|
| No |
|
| No | local embedder |
| No | none |
| No |
|
| No |
|
| No |
|
| No |
|
| No |
|
Resolution order, security notes, and examples are in docs/CONFIGURATION.md.
Project Structure
Mantis-MCP/
├── src/
│ ├── index.ts # Entry point, configuration, MantisBT HTTP client, tool registration
│ ├── vectorStore.ts # Embeddings, issue metrics, persistence, search, efficiency analytics
│ └── test.ts # Integration tests (node:test) with a stubbed MantisBT API
├── docs/
│ ├── ARCHITECTURE.md # Modules, request lifecycle, vector store internals, design decisions
│ ├── TOOLS.md # Reference for all 25 tools
│ ├── CONFIGURATION.md # Environment variables, resolution order, client setup
│ ├── TESTING.md # Test strategy, cases, and how to add tests
│ └── designs/ # Design records for the MCP server and the analytics feature
├── .env.example # Configuration template
├── package.json
└── tsconfig.jsonGenerated files (dist/, .env, .mantis-vector-store.json) are git-ignored.
Documentation
Document | Contents |
How the server is built and why | |
Tool-by-tool parameter reference | |
Setup and environment variables | |
Running and extending the test suite | |
Design specification for the MCP server | |
Design specification for the vector store and analytics |
Development
npm run dev # TypeScript in watch mode
npm run build # Compile src/ to dist/
npm start # Run the compiled server
npm test # Run the test suiteLimitations
The vector store is a single JSON file loaded into memory. It suits thousands of issues, not millions.
The default embedder captures shared words and character patterns, not meaning. Use an external embedding endpoint if you need synonym-level matching.
Changing the embedding mode requires re-running
sync_issues_to_vector_store.The server exposes the MantisBT API as the authenticated user. Its permissions are the permissions of the token.
Security
Issue content is untrusted. Anyone who can file or comment on an issue can plant instructions that your AI client may follow (prompt injection). Require human approval for write tools (
update_issue,add_issue_note,add_issue_attachment,create_issue).Deletes are off by default.
delete_issue,delete_issue_note,delete_issue_relationship, and tag removal fail unlessMANTIS_ALLOW_DELETE=true.Read-only mode. Set
MANTIS_READ_ONLY=trueto reject every write call; this is the strongest mitigation against prompt injection through issue text.Use a least-privilege token, ideally a dedicated read-only account.
Vector store is plaintext.
.mantis-vector-store.jsonholds issue content unencrypted; it is written with mode0600on POSIX and with anicaclsACL restricted to the current user on Windows (best effort). It is not encrypted.https is required for
MANTIS_BASE_URLandMANTIS_EMBEDDING_API_URL(localhost excepted); redirects are not followed.Embedding API is opt-in. When configured, issue text leaves your machine.
The vector store holds issue text. It is written with owner-only permissions and git-ignored; keep it out of shared folders.
Report vulnerabilities as described in SECURITY.md.
Disclaimer
This is an unofficial, community project. It is not affiliated with or endorsed by MantisBT or its maintainers.
License
MIT. You may use, copy, and modify this project freely, including commercially, as long as the license notice is kept.
Citation
If you use this project, please credit it with a link to the repository: https://github.com/coelho-coie/mantisbt-mcp-Unofficial. This is a request, not a license requirement; the license stays MIT.
Available Tools
25 toolsadd_issue_attachmentC
Adds an attachment file (Base64) to an existing issue.
Inputs: filename (required), issue_id (required), content_base64 (required).
add_issue_noteC
Adds a note/comment to an issue in MantisBT, with visibility support (public/private) and time tracking.
Inputs: text (required), issue_id (required), view_state, time_tracking_duration.
add_issue_relationshipC
Creates a relationship between two issues (e.g. related-to, duplicate-of, parent-of, child-of, has-duplicate).
Inputs: issue_id (required), target_issue_id (required), relationship_type.
analyze_project_efficiencyA
Analyzes project engineering efficiency via the MantisBT issue vector store: computes resolution rate, mean/P50/P90 lead time, rework rate (reopens), assignee ping-pong, stagnant/overdue issues, efficiency per developer, semantic clusters of recurring bottlenecks, and an Efficiency Score (0-100) with actionable diagnostics.
Inputs: auto_sync, handler_id, project_id, max_sync_pages, +2 more.
attach_issue_tagsC
Attaches one or more tags to an issue.
Inputs: tags (required), issue_id (required).
check_mantis_connectionA
Validates connectivity and authentication with the MantisBT REST API (including automatic detection of /api/rest/index.php when mod_rewrite is disabled).
Inputs: no named parameters.
create_issueC
Creates a new issue in MantisBT.
Inputs: summary (required), project_id (required), description (required), tags, +9 more.
create_project_versionC
Creates a new version within a MantisBT project.
Inputs: name (required), project_id (required), obsolete, released, +2 more.
delete_issueC
Deletes a MantisBT issue by ID.
Inputs: issue_id (required).
delete_issue_noteC
Removes a specific note/comment from an issue.
Inputs: note_id (required), issue_id (required).
delete_issue_relationshipC
Removes a relationship between issues.
Inputs: issue_id (required), relationship_id (required).
detach_issue_tagC
Removes a tag from an issue by tag ID.
Inputs: tag_id (required), issue_id (required).
get_current_userB
Returns the full profile of the authenticated user (/users/me) in MantisBT.
Inputs: no named parameters.
get_issue_attachmentB
Downloads the content (text or Base64) of a specific issue attachment for inspection by the LLM.
Inputs: issue_id (required), attachment_id (required).
get_issue_full_contextB
Gets all details of a specific issue by ID (description, notes, history, attachments, custom fields and relationships).
Inputs: issue_id (required), include_history.
get_mantis_configC
Gets configuration options from the MantisBT server (e.g. status_enum_string, priority_enum_string, workflows).
Inputs: options (required), user_id, project_id.
get_my_unresolved_assigned_contextB
MAIN FUNCTION: Collects everything about all issues assigned to the user (or to a specific user) that are not yet resolved/closed. Returns the full description, steps to reproduce, additional information, complete notes/comments, custom fields, relationships, tags, attachment metadata, change history, and an executive summary grouped by project/priority/status to give the LLM full context.
Inputs: filter_id, max_pages, project_id, include_history, +3 more.
get_projectB
Gets full details of a specific project by ID.
Inputs: project_id (required).
list_filtersA
Lists all saved filters available to the user in MantisBT.
Inputs: no named parameters.
list_issuesC
Lists and filters MantisBT issues by project, saved filter, assignee (handler), reporter, status or text search.
Inputs: page, filter_id, page_size, handler_id, +3 more.
list_projectsA
Lists all accessible MantisBT projects, including categories, versions and custom fields.
Inputs: no named parameters.
monitor_issueA
Adds a user (or the authenticated user if omitted) as a monitor/observer of an issue.
Inputs: issue_id (required), username.
search_vector_issuesB
Runs a semantic search by cosine similarity over the MantisBT issue mini vector store, combining embeddings and metadata filters to find recurring bugs, similar root causes or technical history.
Inputs: query (required), top_k, handler_id, project_id, +2 more.
sync_issues_to_vector_storeA
Collects MantisBT issues, computes vector embeddings (local 256d or external API) and lifecycle metrics (lead time, reopens, assignment ping-pong, stagnation), and persists everything to the local mini vector store for semantic search and efficiency analysis.
Inputs: filter_id, max_pages, project_id, hydrate_individual_issues.
update_issueB
Updates any field of an existing MantisBT issue (status, assignee/handler, priority, severity, resolution, texts, versions, tags or custom fields).
Inputs: issue_id (required), summary, handler_id, description, +10 more.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 25 tools
Most tools target a clearly distinct resource+action (tags, notes, relationships, attachments, vector search, analytics). The main overlaps are update_issue (which claims it can also change tags/custom fields) versus attach_issue_tags, and get_issue_full_context versus the aggregate get_my_unresolved_assigned_context, though descriptions do clarify the latter. An agent can pick correctly in nearly all cases.
Almost everything follows a consistent verb_noun snake_case pattern (list_projects, create_issue, delete_issue_note, add_issue_relationship). Minor deviations exist: attach_issue_tags vs detach_issue_tag (singular/plural mismatch) and the sentence-style get_my_unresolved_assigned_context. Still highly predictable overall.
25 tools is at the upper edge, but the domain legitimately spans issues, projects, versions, tags, notes, relationships, attachments, config, and vector/analytics features, so each tool roughly earns its place. Slightly heavy and could be consolidated (e.g. attach/detach tag pairs), but not bloated for the stated purpose.
Issue lifecycle and notes/relationships are well covered, but there are notable gaps: no delete_issue_attachment, no create/update/delete project, no list/create tags, and versions only support create. These holes will force agents into dead ends on common maintenance tasks, even if core bug-tracking workflows work.
Maintenance
Related MCP Connectors
Issue tracking for software projects: issues, epics, releases, docs and boards, from your AI.
Task and bug tracker for AI coding agents: 75 tools to file, triage and update work.
Connects AI assistants to TrackingTime for querying time entries, projects, tasks, customers, and team data using natural language.
Let AI agents list, read and resolve Bugsly error-tracking issues and check monitors.
Related MCP Servers
- 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
- AlicenseCqualityDmaintenanceEnables AI assistants to interact with Redmine instances, managing issues, projects, and metadata through natural language commands.1218 npmMIT
- AlicenseAqualityCmaintenanceProvides AI assistants with direct access to MantisBT issue trackers via the REST API, enabling reading, updating, resolving, and semantically searching issues.2015 npmMIT
- AlicenseAqualityCmaintenanceEnables AI agents to interact with Redmine through intent-shaped tools for issue tracking, time logging, project management, and more.1910 npm20MIT