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.

View on codeberg.org

dpesch/mantisbt-mcp-server

Watch 0

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.

bugtracker claude claude-code issue-tracker mantis mantisbt mcp mcp-server model-context-protocol

163 commits1 branch32 tags 2.5 MiB

  • TypeScript 95.5%
  • JavaScript 4.5%

Find a file

HTTPS

Dominik Pesch d685e5c050 All checks were successful CI / Publish / ci (push) Has been skipped Details CI / Publish / publish (push) Has been skipped Details chore: release v1.10.22026-05-03 09:48:41 +02:00
.giteaci: add GitHub release step to publish workflow2026-03-18 18:59:31 +01:00
.github/workflowsci: Add GitHub Actions workflow for CI status2026-05-02 19:14:25 +02:00
docsdocs: Update docs and server.json for v1.10.02026-04-11 09:10:11 +02:00
scriptsfix: Skip existing Codeberg tags via batch ls-remote in pre-push hook2026-03-27 15:41:14 +01:00
srcdocs: Improve tool descriptions to boost Glama quality scores2026-05-03 09:22:47 +02:00
testsfeat: Add view_url to all issue and note responses2026-04-11 08:59:56 +02:00
.gitignoreIgnoriere temporäre playwright-inhalte2026-04-26 09:23:25 +02:00
.npmignorechore: release v1.0.02026-03-15 14:10:54 +01:00
CHANGELOG.mdchore: release v1.10.22026-05-03 09:48:41 +02:00
CLAUDE.mddocs: trim CLAUDE.md from 254 to 76 lines2026-03-18 10:28:14 +01:00
CONTRIBUTING.mddocs: add PR template and note about cherry-pick integration workflow2026-03-15 21:00:37 +01:00
glama.jsonchore: add glama.json for Glama MCP directory listing2026-03-18 18:48:12 +01:00
LICENSEchore: release v1.0.02026-03-15 14:10:54 +01:00
package-lock.jsonchore: Fix all npm audit vulnerabilities2026-05-02 21:40:55 +02:00
package.jsonchore: release v1.10.22026-05-03 09:48:41 +02:00
README.de.mddocs: Update CHANGELOG and README for improved tool descriptions2026-05-03 09:43:36 +02:00
README.mddocs: Update CHANGELOG and README for improved tool descriptions2026-05-03 09:43:36 +02:00
server.jsonchore: release v1.10.22026-05-03 09:48:41 +02:00
tsconfig.build.jsonchore: release v1.0.02026-03-15 14:10:54 +01:00
tsconfig.jsonchore: release v1.0.02026-03-15 14:10:54 +01:00
vitest.config.tschore: release v1.0.02026-03-15 14:10:54 +01:00

README.md

MantisBT MCP Server

npm version license MCP Badge 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

VariableRequiredDefaultDescription
MANTIS_BASE_URL✅–Base URL of your MantisBT installation. Both https://your-mantis.example.com and https://your-mantis.example.com/api/rest are accepted — the /api/rest suffix is normalized automatically.
MANTIS_API_KEY✅–API token for authentication
MANTIS_CACHE_DIR–~/.cache/mantisbt-mcpDirectory for the metadata cache
MANTIS_CACHE_TTL–3600Cache lifetime in seconds
TRANSPORT–stdioTransport mode: stdio or http
PORT–3000Port for HTTP mode
MCP_HTTP_HOST–127.0.0.1Bind 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–falseSet to true to enable semantic search
MANTIS_SEARCH_BACKEND–vectraVector store backend: vectra (pure JS) or sqlite-vec (requires manual install)
MANTIS_SEARCH_DIR–{MANTIS_CACHE_DIR}/searchDirectory for the search index
MANTIS_SEARCH_MODEL–Xenova/paraphrase-multilingual-MiniLM-L12-v2Embedding model name (downloaded once on first use, ~80 MB)
MANTIS_SEARCH_THREADS–1Number 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

ToolDescription
get_issueRetrieve an issue by its numeric ID
get_issuesRetrieve multiple issues by ID in one call (1–50 IDs); missing or inaccessible IDs return null at their position instead of failing the call
list_issuesFilter issues by project, status, author, and more; optional select for field projection and status for client-side status filtering — canonical English status names (e.g. "new", "resolved") are matched by ID, making the filter language-independent on localized installations
create_issueCreate 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_issueUpdate an existing issue; enum fields (status, priority, severity, resolution, reproducibility) accept canonical English names, localized names, or numeric IDs — the server resolves names to IDs automatically
delete_issueDelete an issue

Notes

ToolDescription
list_notesList all notes of an issue
add_noteAdd a note to an issue
delete_noteDelete a note

Attachments

ToolDescription
list_issue_filesList attachments of an issue
upload_fileUpload a file to an issue — either by local file_path or Base64-encoded content + filename

Relationships

ToolDescription
add_relationshipCreate 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_relationshipRemove a relationship from an issue (use the id from the relationship object, not the type)

Monitors

ToolDescription
add_monitorAdd a user as a monitor of an issue
remove_monitorRemove a user as a monitor of an issue

Tags

ToolDescription
list_tagsList all available tags; falls back to the metadata cache when GET /tags returns 404 (run sync_metadata first to populate)
attach_tagsAttach tags to an issue
detach_tagRemove a tag from an issue

Projects

ToolDescription
list_projectsList all accessible projects; returns normalized project data (consistent with sync_metadata cache)
get_project_versionsGet versions of a project; optional obsolete and inherit booleans to include obsolete or parent-inherited versions
get_project_categoriesGet categories of a project
get_project_usersGet users of a project
find_project_memberSearch project members by name, real name, or email (case-insensitive substring match); optional query and limit (default 10, max 100); cache-first

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.

ToolDescription
search_issuesNatural 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; optional highlight (boolean, default false) adds a highlights field per result with keyword-matched excerpts from summary and description (matched terms shown in **bold**)
rebuild_search_indexBuild or update the search index; full: true clears and rebuilds from scratch
get_search_index_statusReturn 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
DependenciesNone (pure JS)Requires native build tools
InstallIncludednpm install sqlite-vec better-sqlite3
Best forUp to ~10,000 issues10,000+ issues
PerformanceFast enough for most setupsFaster 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

ToolDescription
get_issue_fieldsReturn all field names valid for the select parameter of list_issues
get_metadataRetrieve a compact metadata summary: project/tag counts and per-project user/version/category counts; use get_metadata_full for complete arrays
get_metadata_fullReturn the full raw metadata cache as minified JSON (all projects with complete fields, users/versions/categories per project, all tags)
sync_metadataRefresh the metadata cache
list_filtersList saved filters
get_current_userRetrieve your own user profile
list_languagesList available languages
get_configShow server configuration (base URL, cache TTL)
get_issue_enumsReturn 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_versionGet MantisBT version and check for updates
get_mcp_versionReturn the version of this mantisbt-mcp-server instance

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.

Resource URIDescription
mantis://meProfile of the authenticated API user (live fetch)
mantis://projectsAll accessible MantisBT projects as a compact list (cache-backed, refreshed via sync_metadata)
mantis://projects/{id}Combined project view: project fields + users + versions + categories in one call; cache-first, list-support for enumerating all available project URIs
mantis://enumsValid values for all issue enum fields: severity, priority, status, resolution, reproducibility (live fetch)

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.

PromptRequired argsOptional argsDescription
create-bug-reportproject_id, category, summary, descriptionsteps_to_reproduce, expected, actual, environmentGuides through a structured bug report and calls create_issue
create-feature-requestproject_id, category, summary, descriptionuse_caseGuides through a feature request and calls create_issue
summarize-issueissue_id–Fetches an issue via get_issue and returns a concise summary
project-statusproject_id–Lists issues via list_issues and generates a status report grouped by severity

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

Related Servers

NotebookLM Web Importer

Import web pages and YouTube videos to NotebookLM with one click. Trusted by 200,000+ users.

Install Chrome Extension