Mantisbt MCP Server

What @dpesch/mantisbt-mcp-server MCP server does

The @dpesch/mantisbt-mcp-server MCP server gives an MCP client access to a MantisBT installation through its REST API. It supports issue lookup and filtering, bulk retrieval by ID, issue creation, updates, and deletion. Issue operations can use field projection to reduce response size, and status filtering uses canonical English names while resolving them to IDs for localized MantisBT installations.

The server also covers related issue-management tasks. Agents can list and modify notes, inspect and upload attachments, create or remove issue relationships, manage monitors, and attach or detach tags. Project-oriented tools list accessible projects, users, categories, and versions. Version tools can create, update, release, or permanently delete project versions, subject to the configured MantisBT permissions.

How it works

The server sends requests to the configured MantisBT REST API and exposes the results as MCP tools. Enum fields can be supplied as canonical English names, localized names, or numeric IDs depending on the operation. For issue creation, get_issue_enums can be used to inspect valid values and labels. Usernames can also be resolved to project members for issue assignment.

Attachments can be uploaded from a local path, with the server reading and encoding the file, or by passing Base64 content and a filename. Semantic search is optional. When enabled, the server builds an embedding-based index using the configured model and vector-store backend. Metadata and search indexes use configurable local directories and cache lifetimes.

Setup and configuration

To run the @dpesch/mantisbt-mcp-server MCP server, use Node.js 22 or newer, MantisBT 2.23 or newer with its REST API enabled, and an API token created in MantisBT under My Account and API Tokens. The minimum configuration defines:

• MANTIS_BASE_URL: the MantisBT host or REST API base URL.
• MANTIS_API_KEY: the token used for authentication.

The package can be launched with npx -y @dpesch/mantisbt-mcp-server from an MCP client configuration, or built locally with the repository's initialization and build commands and then started with Node. Stdio is the default transport. HTTP mode uses TRANSPORT=http, PORT, and MCP_HTTP_HOST; it requires MCP_HTTP_TOKEN for bearer authentication on /mcp. The health endpoint remains public.

MANTIS_USE_INDEX_PHP supports installations without URL rewriting. Cache location and lifetime are controlled by MANTIS_CACHE_DIR and MANTIS_CACHE_TTL. File uploads can be restricted with MANTIS_UPLOAD_DIR; in HTTP mode, server-side file paths are disabled unless this setting is provided, so clients should use Base64 content otherwise.

Tools and capabilities

The available tool groups include:

• Issues: get_issue, get_issues, list_issues, create_issue, update_issue, and delete_issue.
• Notes and attachments: list_notes, add_note, delete_note, list_issue_files, and upload_file.
• Relationships and monitors: add_relationship, remove_relationship, add_monitor, and remove_monitor.
• Tags and projects: tag management, project listing, project users and categories, and project-member lookup.
• Versions: retrieve, create, update, release, and delete project versions.

Issue updates can include a note in the same operation, and custom fields are supported for issue creation and updates. Missing or inaccessible IDs in a multi-issue lookup return null in their original positions rather than failing the whole call.

Limitations and notes

The @dpesch/mantisbt-mcp-server MCP server depends on the capabilities and permissions of the connected MantisBT installation. Version creation and modification require the relevant manage_project_threshold permission. Deleting a version is irreversible and clears related version fields from referencing issues; marking it obsolete is the non-destructive alternative.

HTTP mode must not be started without MCP_HTTP_TOKEN, and the default bind address is localhost. Set MCP_HTTP_HOST explicitly for Docker or remote access. The semantic-search backend sqlite-vec requires manual installation, while the default vectra backend is implemented in JavaScript. The embedding model is downloaded on first use.