Skip to content

Repository files navigation

MantisBT Plugin for Claude Code

Deutsche Version

A Claude Code plugin that integrates the MantisBT MCP Server into Claude Code, so you can research, create, and manage MantisBT bug tracker issues directly from a Claude Code session.

What's included

  • MCP server — launches @dpesch/mantisbt-mcp-server via npx, connecting to your MantisBT instance's REST API
  • Skills
    • /mantisbt:research — research issues, bugs, and project history (read-only)
    • /mantisbt:create — guided creation of a new issue (bug, feature, task)
    • /mantisbt:sync — check or refresh the MantisBT metadata cache
    • /mantisbt:setup — guided setup, status check, and troubleshooting for the optional semantic search
  • Agent
    • mantis-researcher — a read-only sub-agent for token-intensive research (bulk lookups, cross-project searches, large result sets), isolated from the main conversation

Requirements

  • A MantisBT instance with the REST API enabled
  • A MantisBT API token (MantisBT → Profile → API Tokens)
  • Node.js 22 or newer with npx on the machine running Claude Code (used to launch the MCP server; older versions are end-of-life and no longer tested by the MCP server)

Installation

This repository is itself a plugin marketplace (11com7-plugins). Add it in Claude Code, then install the plugin from it:

/plugin marketplace add dpesch/mantisbt-claude-plugin
/plugin install mantisbt@11com7-plugins

On first use, Claude Code will prompt you for two settings (userConfig):

Setting Description
MantisBT API URL Base URL of your MantisBT REST API, e.g. https://bugs.example.com/api/rest
API Key Your MantisBT API token (stored securely, never shown in plain text)

MantisBT without URL rewriting

If your MantisBT server has no URL rewriting enabled (Apache without mod_rewrite, IIS without the URL Rewrite module), its REST API is only reachable through the index.php front controller. In that case, enter the URL exactly as it works in your browser:

https://bugs.example.com/api/rest/index.php

The MCP server detects the index.php suffix and routes every request through it — no further configuration needed. Alternatively, set MANTIS_USE_INDEX_PHP=true in the environment that launches Claude Code; an explicitly set variable always takes precedence over the URL-based detection.

Optional: local semantic search

The underlying MCP server can optionally build a local, offline semantic search index over your MantisBT issues, so /mantisbt:research can answer natural-language queries (e.g. "login fails after password reset") instead of relying on exact keyword matches. The embedding model (~80 MB) is downloaded once on first use and runs entirely offline — no external API calls.

It's disabled by default. To enable it, set these environment variables for the process launching Claude Code (they are not part of this plugin's userConfig, since they configure the MCP server itself):

Variable Default Purpose
MANTIS_SEARCH_ENABLED false Set to true to enable semantic search
MANTIS_SEARCH_BACKEND vectra vectra (pure JS, no extra install) or sqlite-vec (faster for 10,000+ issues, requires npm install sqlite-vec better-sqlite3)
MANTIS_SEARCH_DIR {MANTIS_CACHE_DIR}/<instance>/search Base directory for the search index; an explicit value also gets a subdirectory per MantisBT instance and API key
MANTIS_SEARCH_MODEL Xenova/paraphrase-multilingual-MiniLM-L12-v2 Embedding model name
MANTIS_SEARCH_THREADS 1 ONNX threads used when indexing; 4 is a good value on machines with 4 or more cores

See the MantisBT MCP Server README for details, or just run /mantisbt:setup — it checks whether semantic search is active and walks you through enabling it if not.

Optional: limit the offered tools

Since v1.15.0 the MCP server can offer fewer tools — this keeps the model's context shorter and can rule out destructive operations. Like the search variables, these are environment variables for the process launching Claude Code, not part of the plugin's userConfig:

Variable Default Purpose
MANTIS_TOOLSETS all groups Comma-separated list of tool groups to offer: issues, notes, links, files, projects, versions, meta, search
MANTIS_DISABLE_DESTRUCTIVE false Set to true to hide every delete/remove tool (delete_issue, delete_note, delete_version, remove_relationship, remove_monitor)

MANTIS_DISABLE_DESTRUCTIVE=true is safe with every skill in this plugin, since none of them deletes anything. If you set MANTIS_TOOLSETS, keep at least issues,projects,meta — the skills and the mantis-researcher agent rely on them; add links for tag lookups and search for semantic search. Hidden tools answer with "Tool … not found". See the MantisBT MCP Server README for the full group-to-tool mapping.

Usage

/mantisbt:research what's the status of issue 1234?
/mantisbt:create file a bug: login fails after password reset
/mantisbt:sync --info
/mantisbt:setup

You can also just describe what you need in natural language ("find open P1 bugs in project X", "create a feature request for dark mode") — the relevant skill is triggered automatically based on context.

Versioning

The plugin version (.claude-plugin/plugin.json) mirrors the MantisBT MCP server version pinned in .mcp.json — plugin v1.18.2 ships MCP server v1.18.2. Releases that don't change the pin carry a build-metadata suffix instead (e.g. 1.18.2+ci.1). See DEVELOPMENT.md for the full rules and the release process.

Privacy

This plugin has no backend of its own — see PRIVACY.md for what data it handles and how.

License

MIT © Dominik Pesch

Releases

Packages

Contributors