README.md
Integrates MantisBT bug tracker into Claude and other MCP clients
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 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
| 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 <token>. 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. |
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 |
Remo |
Tools (12)
get_issueRetrieve an issue by its numeric IDlist_issuesFilter issues by project, status, author, and morecreate_issueCreate a new issueupdate_issueUpdate an existing issuedelete_issueDelete an issuelist_notesList all notes of an issueadd_noteAdd a note to an issuedelete_noteDelete a notelist_issue_filesList attachments of an issueupload_fileUpload a file to an issueadd_relationshipCreate a relationship between two issuesremove_relationshipRemove a relationship between two issuesEnvironment Variables
MANTIS_BASE_URLrequiredBase URL of the MantisBT REST APIMANTIS_API_KEYrequiredAPI token for authenticationMANTIS_CACHE_DIRDirectory for the metadata cacheMANTIS_SEARCH_ENABLEDSet to true to enable semantic searchConfiguration
claude_desktop_config.json
{"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"}}}}Try it
→List all open issues assigned to me in the current project.
→Create a new bug report for the login page crash with high severity.
→Add a note to issue #123 explaining that I have reproduced the error.
→Find all issues related to the database migration project.
→Upload the log file at ./debug.log to issue #456.