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)

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"
      }
    }
  }
}

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"
      }
    }
  }
}

Configuration

Environment variables

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 hide delete_issue, delete_note, delete_version, remove_relationship, and remove_monitor regardless of the active groups

Hidden tools are not listed and return "Tool … not found" when called.

¹ 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

Notes

Attachments

Relationships

Monitors

Tags

Projects

Semantic search (optional)

Instead of exact keyword matching, semantic search understands the meaning behind a query. 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).

Activate with MANTIS_SEARCH_ENABLED=true.

Which backend to choose?

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-vec

Metadata & system

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):

¹ 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 benchmark

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

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.

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

Every /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.

Health check: GET http://localhost:3456/health (always public, no token required)

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)

License

MIT – see LICENSE

Contributing

Contributions welcome! Please read CONTRIBUTING.md. Repository: codeberg.org/dpesch/mantisbt-mcp-server