Skip to main content
Glama

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_context gathers 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 without mod_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_store again.

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 test

Create a .env file from the template:

cp .env.example .env

Then 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 -v

Expected: 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-MCP

If it is already on disk, change into its directory. The directory must contain package.json and src/.

Step 3: Install dependencies

npm install

Expected: the command exits with code 0. Dependencies are @modelcontextprotocol/sdk and zod. Development dependencies are typescript and @types/node.

Step 4: Build

npm run build

Expected: the command exits with code 0 and creates dist/index.js. Verify the file exists before continuing.

Step 5: Run the tests

npm test

Expected 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 .env

On 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

MANTIS_BASE_URL

The MantisBT site URL, for example https://mantis.example.com.

MANTIS_API_TOKEN

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:

  1. Call sync_issues_to_vector_store with max_pages: 2 to test on a small set.

  2. If that succeeds, the index can be grown with larger max_pages values.

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

npm install fails

Node.js and npm versions, network access

Upgrade Node.js to 18 or later. Retry.

npm run build fails

Output of tsc

Report the TypeScript error. Do not edit source files to make it pass without the user's approval.

Set MANTIS_BASE_URL and MANTIS_API_TOKEN ...

.env exists and has real values; client env block

Fix the values in .env or the client env block.

HTTP 401

Token value

Ask the user to create a new token in MantisBT and update it.

HTTP 404 on every call

MANTIS_BASE_URL value

The server already tries /api/rest and then /api/rest/index.php. Confirm the site URL is correct and that the REST API is enabled.

Client shows no tools

Path in client config is absolute and correct; client was restarted

Fix the path, then restart the client.

node: command not found in the client

node is not on the client's PATH

Put the full path to the node executable in command.

Installation checklist

  • Node.js 18 or later is installed

  • npm install exits with code 0

  • npm run build exits with code 0 and dist/index.js exists

  • npm test reports 4 passing tests

  • .env exists with real MANTIS_BASE_URL and MANTIS_API_TOKEN

  • The MCP client config points to the absolute path of dist/index.js

  • The client was restarted

  • check_mantis_connection succeeds

Tools at a Glance

Group

Tools

Context for LLMs

get_my_unresolved_assigned_context

Vector store and analytics

sync_issues_to_vector_store, search_vector_issues, analyze_project_efficiency

Issues

get_issue_full_context, list_issues, create_issue, update_issue, delete_issue

Notes and time tracking

add_issue_note, delete_issue_note

Relationships, tags, attachments, monitoring

add_issue_relationship, delete_issue_relationship, get_issue_attachment, add_issue_attachment, attach_issue_tags, detach_issue_tag, monitor_issue

Projects, versions, filters, users, settings

check_mantis_connection, list_projects, get_project, create_project_version, list_filters, get_current_user, get_mantis_config

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, and user_id are integers. Look them up with list_projects, get_current_user, or list_issues first.

  • Prefer the narrowest tool. Use get_issue_full_context for one issue, not list_issues followed 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: true contains {"error": "..."}. Quote the message to the user and stop that branch. Do not retry the same call unchanged.

  • Confirm before destructive actions. delete_issue and delete_issue_note cannot 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?"

get_my_unresolved_assigned_context

"What's going on with issue #42?"

get_issue_full_context

"Show open bugs in project 3"

list_issues with project_id and only_unresolved

"Have we seen this problem before?"

sync_issues_to_vector_store, then search_vector_issues

"How healthy is project 3?"

analyze_project_efficiency

"Open a bug for X"

create_issue

"Mark #42 as in progress for Ana"

update_issue

"Log 1h30 on #42"

add_issue_note with time_tracking_duration

"Is #42 a duplicate of #17?"

add_issue_relationship with relationship_type: "duplicate-of"

3. Workflows

A. Daily triage of my work

  1. Call get_my_unresolved_assigned_context. Use the executive summary for an overview.

  2. For the top items, call get_issue_full_context with each issue_id to read the description and notes.

  3. 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

  1. get_issue_full_context with issue_id.

  2. search_vector_issues with query set to the issue summary, and only_unresolved: false to find past solutions. Results need a prior sync_issues_to_vector_store. If the store is empty, the result contains an explanatory message.

  3. Report the closest matches with their id and 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

  1. sync_issues_to_vector_store with project_id and max_pages. Start small (max_pages: 2) to check the result.

  2. 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

  1. analyze_project_efficiency with project_id. Leave auto_sync at true unless the user says not to sync.

  2. Report the Efficiency Score, the throughput and lead time figures, and the diagnostics list in that order.

  3. Use top_stale_unresolved_issues and assignee_efficiency to 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

  1. Confirm the project_id and category_name with list_projects, which returns categories.

  2. create_issue with a clear summary and a full description. Include steps_to_reproduce when the user provides them.

  3. Use the returned id in later calls. Use update_issue only 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

  1. add_issue_note with text, view_state (public unless the user says private), and time_tracking_duration in HH:MM format when the user gives hours.

  2. 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

  1. get_issue_full_context lists attachment metadata (id, filename, size_bytes, content_type).

  2. Call get_issue_attachment with issue_id and attachment_id only 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

Set MANTIS_BASE_URL and MANTIS_API_TOKEN

Configuration missing

Add both variables to the MCP client env block or the server .env.

HTTP 401

Token invalid or expired

Create a new API token in MantisBT.

HTTP 403

Account lacks permission

The token's account cannot perform this action.

HTTP 404

Wrong ID, or REST path issue

Verify the ID with list_issues or list_projects. Run check_mantis_connection.

Issue #N not found.

ID does not exist

Ask the user to confirm the ID.

"No issues found in the vector store"

Index is empty

Run sync_issues_to_vector_store first.

Configuration

Variable

Required

Default

MANTIS_BASE_URL

Yes

none

MANTIS_API_TOKEN

Yes

none

MANTIS_RESOLVED_THRESHOLD

No

80

MANTIS_VECTOR_DB_PATH

No

.mantis-vector-store.json

MANTIS_EMBEDDING_API_URL

No

local embedder

MANTIS_EMBEDDING_API_KEY

No

none

MANTIS_EMBEDDING_MODEL

No

text-embedding-3-small

MANTIS_ALLOW_EXTERNAL_EMBEDDINGS

No

false (external embeddings need this opt-in)

MANTIS_ALLOW_DELETE

No

false (all DELETE calls blocked)

MANTIS_ALLOW_HTTP

No

false (non-https URLs rejected, except localhost)

MANTIS_READ_ONLY

No

false (set true to block all write calls: POST, PATCH, PUT, DELETE)

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.json

Generated files (dist/, .env, .mantis-vector-store.json) are git-ignored.

Documentation

Document

Contents

ARCHITECTURE.md

How the server is built and why

TOOLS.md

Tool-by-tool parameter reference

CONFIGURATION.md

Setup and environment variables

TESTING.md

Running and extending the test suite

designs/mantisbt-mcp.md

Design specification for the MCP server

designs/vector-efficiency-analytics.md

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 suite

Limitations

  • 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 unless MANTIS_ALLOW_DELETE=true.

  • Read-only mode. Set MANTIS_READ_ONLY=true to 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.json holds issue content unencrypted; it is written with mode 0600 on POSIX and with an icacls ACL restricted to the current user on Windows (best effort). It is not encrypted.

  • https is required for MANTIS_BASE_URL and MANTIS_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 tools
add_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

    B3/5.0

    Scored across 25 tools

    Disambiguation4/5

    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.

    Naming Consistency4/5

    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.

    Tool Count4/5

    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.

    Completeness3/5

    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

    ActivityMaintained
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers