What can you do with this server?

The MantisBT MCP Server integrates MantisBT bug tracking into MCP-capable clients (e.g., Claude Code), enabling full issue lifecycle management and more. Issue Management * Get, list (with filtering by project, status, assignee, reporter, saved filter, and field projection), create, update, and delete issues Notes & Attachments * List, add (public or private), and delete notes/comments on issues * List attachments and upload files via local path or Base64-encoded content Relationships & Monitoring * Add/remove relationships between issues (duplicate_of, related_to, parent_of, child_of, has_duplicate) * Add/remove users as issue monitors/watchers for email notifications Tags * List available tags; attach (auto-creating if needed) or detach tags from issues Projects * List accessible projects; retrieve project versions, categories, and users (with optional access level filter) Semantic Search (optional, requires MANTIS_SEARCH_ENABLED=true) * Natural language search over issues using offline embedding models (vectra or sqlite-vec backends) * Rebuild the search index (full or incremental) and check index status Metadata & System * Sync and retrieve cached metadata (projects, users, versions, categories) * List saved filters, get current user profile, list supported languages * Retrieve enum values for issue fields (severity, status, priority, resolution, reproducibility) * Get MantisBT and MCP server version information and server configuration Deployment * Supports stdio (local) and HTTP (remote) modes with optional token authentication and configurable file upload restrictions

MantisBT MCP Server

npm version license 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)

Related MCP server: MantisBT MCP Server

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

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

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)

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

Install Server

A

security – no known vulnerabilities

A

license - permissive license

A

quality - confirmed to work

How are these scores calculated?

Resources

Need Help?

Report Issue

Related Servers

Tools

View all tools

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

MantisBT MCP Server

MantisBT MCP Server

Requirements

Installation

Configuration

Environment variables

Config file (fallback)

Available tools

Issues

Notes

Attachments

Relationships

Monitors

Tags

Projects

Semantic search (optional)

Which backend to choose?

Metadata & system

HTTP mode

Development

License

Contributing

Resources

Tools

Latest Blog Posts

MCP directory API