mantis-mcp

MCP (Model Context Protocol) server for MantisBT with CRUD operations and semantic search (RAG) over issues and notes.

Enables natural language queries like "have I ever discussed X with client Y?" across a large MantisBT database (10,000+ issues).

Features

• 8 CRUD tools — list/get/create/update issues, add notes, list projects and users

• 3 semantic search tools — natural language search across all issues and notes, with incremental sync

• Local embeddings — runs entirely offline using Transformers.js (no external API calls for search)

• Multilingual — uses paraphrase-multilingual-MiniLM-L12-v2 model (IT/EN/DE/FR/ES/...)

• Incremental sync — only processes new/updated/deleted issues after the initial sync

Related MCP server: MantisBT MCP Server

Quick Start

1. Install

git clone git@github.com:f-liva/mantis-mcp.git
cd mantis-mcp
npm install
npm run build

2. Setup (automated)

Run the interactive setup script — it detects your platform (WSL, Windows, macOS, Linux), asks for your MantisBT credentials, tests the connection, and configures everything automatically:

./setup.sh setup

This will:

• Prompt for your MantisBT API URL and token

• Test the API connection

• Configure Claude Desktop (claude_desktop_config.json)

• Configure Claude Code (.mcp.json)

• Create the .env file

You can also pass parameters directly:

./setup.sh setup -u "https://mantis.example.com/api/rest" -k "your-api-token"

Or configure only one target:

./setup.sh setup -t desktop   # only Claude Desktop
./setup.sh setup -t cli       # only Claude Code
./setup.sh setup -t both      # both (default)

3. Manual Configuration (alternative)

If you prefer to configure manually:

Claude Desktop

Edit your claude_desktop_config.json:

• Windows: %APPDATA%\Claude\claude_desktop_config.json

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json

• Linux: ~/.config/claude/claude_desktop_config.json

Windows (without WSL):

{
  "mcpServers": {
    "mantis": {
      "command": "node",
      "args": ["C:\\Users\\YOURUSERNAME\\mantis-mcp\\dist\\index.js"],
      "env": {
        "MANTIS_API_URL": "https://mantis.example.com/api/rest",
        "MANTIS_API_KEY": "your-api-token"
      }
    }
  }
}

Windows with WSL:

{
  "mcpServers": {
    "mantis": {
      "command": "wsl",
      "args": ["bash", "-c", "cd /home/YOURUSERNAME/mantis-mcp && node dist/index.js"],
      "env": {
        "MANTIS_API_URL": "https://mantis.example.com/api/rest",
        "MANTIS_API_KEY": "your-api-token"
      }
    }
  }
}

macOS / Linux:

{
  "mcpServers": {
    "mantis": {
      "command": "node",
      "args": ["/absolute/path/to/mantis-mcp/dist/index.js"],
      "env": {
        "MANTIS_API_URL": "https://mantis.example.com/api/rest",
        "MANTIS_API_KEY": "your-api-token"
      }
    }
  }
}

Claude Code (CLI)

Create a .mcp.json in any project directory:

{
  "mcpServers": {
    "mantis": {
      "command": "node",
      "args": ["/absolute/path/to/mantis-mcp/dist/index.js"],
      "env": {
        "MANTIS_API_URL": "https://mantis.example.com/api/rest",
        "MANTIS_API_KEY": "your-api-token"
      }
    }
  }
}

Configuration

Tools Reference

CRUD Tools (8)

Semantic Search Tools (3)

Search Workflow

1. First time: Call sync_index to populate the vector database (may take several minutes for large databases)

2. Search: Use search with natural language queries — results include similarity scores

3. Keep updated: Call sync_index periodically — it performs incremental sync (only changed issues)

Architecture

Claude Desktop / Claude Code
        │
        │ stdio (JSON-RPC)
        ▼
    mantis-mcp server
        │
        ├── CRUD tools ──────► MantisBT REST API
        │
        └── Search tools
              ├── sync ──────► MantisBT REST API → Embeddings → SQLite + sqlite-vec
              └── search ────► Embeddings → sqlite-vec KNN → Ranked results

• Embeddings: Generated locally with Transformers.js (~80MB model downloaded on first use)

• Vector storage: SQLite with sqlite-vec extension for fast cosine similarity search

• Sync: Compares updated_at timestamps to detect changes, then re-embeds only modified issues

License

MIT