MantisBT MCP Server
Integrates MantisBT bug tracker into Claude and other MCP clients via the REST API. Read and manage issues, notes, file attachments, tags, relationships, and monitors — with optional offline semantic search across all issues.
dpesch/mantisbt-mcp-server
Watch 1
Star 0
Fork
You've already forked mantisbt-mcp-server
0
MCP server for MantisBT REST API – read and manage bug tracker issues directly from Claude Code and other MCP-compatible clients.
97 commits1 branch19 tags 1,002 KiB
- TypeScript 94.4%
- JavaScript 5.6%
Find a file
HTTPS
| Dominik Pesch a7be7e8d2f All checks were successful CI / Publish / ci (push) Has been skipped Details CI / Publish / publish (push) Has been skipped Details chore: release v1.5.9 | 2026-03-20 10:54:06 +01:00 | |
|---|---|---|
| .gitea | ci: add GitHub release step to publish workflow | 2026-03-18 18:59:31 +01:00 |
| docs | docs: link cookbook and examples from README and cross-link docs | 2026-03-20 10:49:57 +01:00 |
| scripts | feat: add npm run init and versioned git hook | 2026-03-18 08:00:24 +01:00 |
| src | fix: Validate severity/priority in create_issue against canonical names | 2026-03-20 09:40:16 +01:00 |
| tests | fix: Validate severity/priority in create_issue against canonical names | 2026-03-20 09:40:16 +01:00 |
| .gitignore | chore: release v1.5.6 | 2026-03-18 14:17:08 +01:00 |
| .npmignore | chore: release v1.0.0 | 2026-03-15 14:10:54 +01:00 |
| CHANGELOG.md | chore: release v1.5.9 | 2026-03-20 10:54:06 +01:00 |
| CLAUDE.md | docs: trim CLAUDE.md from 254 to 76 lines | 2026-03-18 10:28:14 +01:00 |
| CONTRIBUTING.md | docs: add PR template and note about cherry-pick integration workflow | 2026-03-15 21:00:37 +01:00 |
| glama.json | chore: add glama.json for Glama MCP directory listing | 2026-03-18 18:48:12 +01:00 |
| LICENSE | chore: release v1.0.0 | 2026-03-15 14:10:54 +01:00 |
| package-lock.json | feat: add npm run init and versioned git hook | 2026-03-18 08:00:24 +01:00 |
| package.json | chore: release v1.5.9 | 2026-03-20 10:54:06 +01:00 |
| README.de.md | docs: link cookbook and examples from README and cross-link docs | 2026-03-20 10:49:57 +01:00 |
| README.md | docs: link cookbook and examples from README and cross-link docs | 2026-03-20 10:49:57 +01:00 |
| server.json | chore: release v1.5.9 | 2026-03-20 10:54:06 +01:00 |
| tsconfig.build.json | chore: release v1.0.0 | 2026-03-15 14:10:54 +01:00 |
| tsconfig.json | chore: release v1.0.0 | 2026-03-15 14:10:54 +01:00 |
| vitest.config.ts | chore: release v1.0.0 | 2026-03-15 14:10:54 +01:00 |
README.md
MantisBT MCP Server
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 ≥ 18
- 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 localclaude_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
| Variable | Required | Default | Description |
|---|---|---|---|
| MANTIS_BASE_URL | ✅ | – | Base URL of the MantisBT REST API |
| MANTIS_API_KEY | ✅ | – | API token for authentication |
| MANTIS_CACHE_DIR | – | ~/.cache/mantisbt-mcp | Directory for the metadata cache |
| MANTIS_CACHE_TTL | – | 3600 | Cache lifetime in seconds |
| TRANSPORT | – | stdio | Transport mode: stdio or http |
| PORT | – | 3000 | Port for HTTP mode |
| MCP_HTTP_HOST | – | 127.0.0.1 | Bind address for HTTP mode. Changed from 0.0.0.0 to 127.0.0.1 — the server now listens on localhost only by default. Set to 0.0.0.0 for Docker or remote access. |
| MCP_HTTP_TOKEN | – | – | When set, the /mcp endpoint requires Authorization: Bearer . The /health endpoint is always public. |
| MANTIS_SEARCH_ENABLED | – | false | Set to true to enable semantic search |
| MANTIS_SEARCH_BACKEND | – | vectra | Vector store backend: vectra (pure JS) or sqlite-vec (requires manual install) |
| MANTIS_SEARCH_DIR | – | {MANTIS_CACHE_DIR}/search | Directory for the search index |
| MANTIS_SEARCH_MODEL | – | Xenova/paraphrase-multilingual-MiniLM-L12-v2 | Embedding model name (downloaded once on first use, ~80 MB) |
| MANTIS_SEARCH_THREADS | – | 1 | Number of ONNX intra-op threads for the embedding model. Default is 1 to prevent CPU saturation on multi-core machines and WSL. Increase only if index rebuild speed matters and the host is dedicated to this workload. |
| MANTIS_UPLOAD_DIR | – | – | Restrict upload_file to files within this directory. When set, any file_path outside the directory is rejected (path traversal attempts via ../ are blocked). Without this variable there is no restriction. |
Config file (fallback)
If no environment variables are set, ~/.claude/mantis.json is read:
{
"base_url": "https://your-mantis.example.com/api/rest",
"api_key": "your-api-token"
}
Available tools
Issues
| Tool | Description |
|---|---|
| get_issue | Retrieve an issue by its numeric ID |
| list_issues | Filter issues by project, status, author, and more; optional select for field projection and status for client-side status filtering |
| create_issue | Create a new issue; severity and priority must be canonical English names (e.g. minor, major, normal, high) — call get_issue_enums to see all valid values and their localized labels; optional handler parameter accepts a username as alternative to handler_id (resolved against project members) |
| update_issue | Update an existing issue |
| delete_issue | Delete an issue |
Notes
| Tool | Description |
|---|---|
| list_notes | List all notes of an issue |
| add_note | Add a note to an issue |
| delete_note | Delete a note |
Attachments
| Tool | Description |
|---|---|
| list_issue_files | List attachments of an issue |
| upload_file | Upload a file to an issue — either by local file_path or Base64-encoded content + filename |
Relationships
| Tool | Description |
|---|---|
| add_relationship | Create a relationship between two issues; optional type_name parameter accepts a string name (e.g. "related_to", "duplicate_of") as alternative to numeric type_id |
| remove_relationship | Remove a relationship from an issue (use the id from the relationship object, not the type) |
Monitors
| Tool | Description |
|---|---|
| add_monitor | Add yourself as a monitor of an issue |
| remove_monitor | Remove a user as a monitor of an issue |
Tags
| Tool | Description |
|---|---|
| list_tags | List all available tags; falls back to the metadata cache when GET /tags returns 404 (run sync_metadata first to populate) |
| attach_tags | Attach tags to an issue |
| detach_tag | Remove a tag from an issue |
Projects
| Tool | Description |
|---|---|
| list_projects | List all accessible projects |
| get_project_versions | Get versions of a project; optional obsolete and inherit booleans to include obsolete or parent-inherited versions |
| get_project_categories | Get categories of a project |
| get_project_users | Get users of a project |
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).
Activate with MANTIS_SEARCH_ENABLED=true.
| Tool | Description |
|---|---|
| search_issues | Natural language search over all indexed issues — returns top-N results with cosine similarity score; optional select (comma-separated field names) enriches each result with the requested issue fields |
| rebuild_search_index | Build or update the search index; full: true clears and rebuilds from scratch |
| get_search_index_status | Return the current fill level of the search index: how many issues are indexed vs. total, and the timestamp of the last sync |
Which backend to choose?
| vectra (default) | sqlite-vec | |
|---|---|---|
| Dependencies | None (pure JS) | Requires native build tools |
| Install | Included | npm install sqlite-vec better-sqlite3 |
| Best for | Up to ~10,000 issues | 10,000+ issues |
| Performance | Fast enough for most setups | Faster for large corpora |
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
| Tool | Description |
|---|---|
| get_issue_fields | Return all field names valid for the select parameter of list_issues |
| get_metadata | Retrieve cached metadata (projects, users, versions, categories) |
| sync_metadata | Refresh the metadata cache |
| list_filters | List saved filters |
| get_current_user | Retrieve your own user profile |
| list_languages | List available languages |
| get_config | Show server configuration (base URL, cache TTL) |
| get_issue_enums | Return valid ID/name pairs for all issue enum fields (severity, status, priority, resolution, reproducibility) — use before create_issue / update_issue to look up correct values; on localized installations each entry may include a canonical_name with the standard English API name |
| get_mantis_version | Get MantisBT version and check for updates |
| get_mcp_version | Return the version of this mantisbt-mcp-server instance |
HTTP mode
For use as a standalone server (e.g. in remote setups):
MANTIS_BASE_URL=... MANTIS_API_KEY=... TRANSPORT=http PORT=3456 node dist/index.js
# With token authentication and 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
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
License
MIT – see LICENSE
Contributing
Contributions welcome! Please read CONTRIBUTING.md. Repository: codeberg.org/dpesch/mantisbt-mcp-server
เซิร์ฟเวอร์ที่เกี่ยวข้อง
Scout Monitoring MCP
ผู้สนับสนุนPut performance and error data directly in the hands of your AI assistant.
Alpha Vantage MCP Server
ผู้สนับสนุนAccess financial market data: realtime & historical stock, ETF, options, forex, crypto, commodities, fundamentals, technical indicators, & more
Photoshop MCP Server
An MCP server for integrating with and automating Adobe Photoshop using the photoshop-python-api.
MCP Tools for Open WebUI
An MCP server for Open WebUI that provides tools for secure Python code execution, time, and SDXL image generation.
Cache Overflow
knowledge network for AI coding agents. Developers connect their agents to a shared pool of verified solutions — saving tokens, reducing debugging time, and getting better results. Solution authors earn when their work helps others.
MCPJam Inspector
A developer tool for testing and debugging MCP servers, supporting STDIO, SSE, and Streamable HTTP protocols.
OpenAPI Schema Explorer
Token-efficient access to OpenAPI/Swagger specs via MCP Resources
ContextStream
Persistent memory and semantic search for AI coding assistants across sessions
Remote MCP Server (Authless)
An example of a remote MCP server deployable on Cloudflare Workers without authentication.
Julia Documentation MCP Server
An MCP server for accessing Julia documentation and source code.
WinCC Unified MCP XT
An MCP server for interfacing with SIEMENS WinCC Unified SCADA systems via their GraphQL API.
SatGate
Open-source API gateway that adds budget enforcement, cost attribution, and monetization to AI agent API calls. MCP-aware with per-tool cost tracking, macaroon-based bearer tokens, L402 Lightning micropayments, and enterprise budget control (Fiat402). The economic firewall for the agent economy.