MantisBT MCP Server

MantisBT MCP サーバー

英語 · ドイツ語

Model Context Protocol（MCP）サーバーです。MantisBT REST APIをClaude Codeやその他のMCP対応クライアントに統合します。エディターから直接、課題の読み取り、作成、更新ができます。

要件

• Node.js ≥ 22
• REST APIが有効なMantisBTのインストール（バージョン2.23以降）
• MantisBT APIトークン（My Account → API Tokensで作成）

インストール

npxを使用（推奨）：

~/.claude/claude_desktop_config.json（Claude Desktop）またはローカルの 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"
      }
    }
  }
}

ローカルビルド：

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"
      }
    }
  }
}

設定

環境変数

変数	必須	デフォルト	説明
MANTIS_BASE_URL	✅	–	MantisBTのインストール先のベースURLです。https://your-mantis.example.comとhttps://your-mantis.example.com/api/restのどちらも指定できます。/api/restサフィックスは自動的に正規化されます。
MANTIS_API_KEY	✅	–	認証用のAPIトークン
MANTIS_USE_INDEX_PHP	–	auto	URLリライトを利用できない場合はtrueに設定します。RESTリクエストでは、/api/rest/の代わりに/api/rest/index.php/を使用します。MANTIS_BASE_URLが/api/rest/index.phpで終わる場合は自動的に検出され、明示的な値が常に優先されます。クックブックを参照してください。
MANTIS_CACHE_DIR	–	~/.cache/mantisbt-mcp	メタデータキャッシュのディレクトリ
MANTIS_CACHE_TTL	–	3600	キャッシュの有効期間（秒）
TRANSPORT	–	stdio	トランスポートモード：stdioまたはhttp
PORT	–	3000	HTTPモードのポート
MCP_HTTP_HOST	–	127.0.0.1	HTTPモードのバインドアドレス。0.0.0.0から127.0.0.1に変更されました。デフォルトではサーバーはlocalhostでのみリッスンするようになりました。Dockerやリモートアクセスで使用する場合は、0.0.0.0に設定してください。
MCP_HTTP_TOKEN	✅（HTTPモード）	–	/mcpエンドポイント用のベアラートークン（Authorization: Bearer <token>）。TRANSPORT=httpの場合は必須です。HTTPモードでは、トークンがないとサーバーは起動を拒否するため、ツールが認証なしで公開されることはありません。stdioモードでは無視されます。/healthエンドポイントは常に公開されています。
MANTIS_SEARCH_ENABLED	–	false	セマンティック検索を有効にするにはtrueに設定します
MANTIS_SEARCH_BACKEND	–	vectra	ベクトルストアのバックエンド：vectra（純粋なJavaScript）またはsqlite-vec（手動インストールが必要）
MANTIS_SEARCH_DIR	–	{MANTIS_CACHE_DIR}/search	検索インデックスのディレクトリ
MANTIS_SEARCH_MODEL	–	Xenova/paraphrase-multilingual-MiniLM-L12-v2	埋め込みモデル名（初回使用時に一度だけダウンロード、約80 MB）
MANTIS_SEARCH_THREADS	–	1	埋め込みモデルのONNX intra-opスレッド数。マルチコアマシンやWSLでCPUが飽和するのを防ぐため、デフォルトは1です。インデックスの再構築速度が重要で、ホストがこの用途専用の場合にのみ増やしてください。
MANTIS_UPLOAD_DIR	–	–	upload_fileのfile_pathを、このディレクトリ内のファイルに制限します（../によるパストラバーサルはブロックされます）。stdioモードでは、これを設定しない限りfile_pathに制限はありません。HTTPモードでは、file_pathはサーバーのファイルシステムから読み取るため、この変数を設定しない限り無効です。HTTPクライアントは代わりにcontent（Base64）パラメーターでアップロードしてください。

利用可能なツール

課題

ツール	説明
get_issue	数値 ID で課題を取得します。レスポンスサイズを削減するためのフィールド投影には、任意の select を指定できます
get_issues	1 回の呼び出しで ID を指定して複数の課題を取得します（1～50 個の ID）。存在しない ID やアクセスできない ID があっても呼び出しは失敗せず、その位置に null を返します
list_issues	プロジェクト、ステータス、作成者などで課題を絞り込みます。フィールド投影用の任意の select と、クライアント側でステータスを絞り込む status を指定できます。正規の英語ステータス名（例："new"、"resolved"）は ID で照合されるため、ローカライズされたインストール環境でも言語に依存しません
create_issue	新しい課題を作成します。severity と priority には正規の英語名（例：minor、major、normal、high）を指定する必要があります。有効な値とそのローカライズされたラベルを確認するには、get_issue_enums を呼び出してください。任意の handler パラメーターには、handler_id の代わりにユーザー名を指定できます（プロジェクトメンバーを対象に解決されます）。カスタムフィールド値を設定するには、任意の custom_fields を指定できます
update_issue	既存の課題を更新します。列挙型フィールド（status、priority、severity、resolution、reproducibility）には、正規の英語名、ローカライズされた名前、または数値 ID を指定できます。サーバーが名前を自動的に ID に解決します。custom_fields と、同じ呼び出しで注記を追加する任意の note パラメーターに対応しています（例：ステータス変更の理由）
delete_issue	課題を削除します

注記

ツール	説明
list_notes	課題のすべての注記を一覧表示します
add_note	課題に注記を追加します
delete_note	注記を削除します

添付ファイル

ツール	説明
list_issue_files	課題の添付ファイルを一覧表示します
upload_file	課題にファイルをアップロードします — 推奨：ローカルの file_path（サーバーが読み込んで自動的にエンコードします）。代替手段：Base64 エンコードされた content と filename（file_path を利用できない場合に限り使用してください）

関連付け

ツール	説明
add_relationship	2 つの課題間に関連付けを作成します。任意の type_name パラメーターには、数値の type_id の代わりに文字列名（例："related_to"、"duplicate_of"）を指定できます
remove_relationship	課題から関連付けを削除します（関連付けオブジェクトの id を使用し、種類は使用しないでください）

モニター

ツール	説明
add_monitor	ユーザーを課題のモニターに追加します
remove_monitor	ユーザーを課題のモニターから削除します

タグ

ツール	説明
list_tags	利用可能なすべてのタグを一覧表示します。GET /tags が 404 を返す場合はメタデータキャッシュにフォールバックします（キャッシュを作成するには、先に sync_metadata を実行してください）
attach_tags	課題にタグを付けます
detach_tag	課題からタグを削除します

プロジェクト

ツール	説明
list_projects	アクセス可能なすべてのプロジェクトを一覧表示します。正規化されたプロジェクトデータを返します（sync_metadata のキャッシュと整合しています）
get_project_versions	プロジェクトのバージョンを取得します。非推奨のバージョンや親から継承したバージョンを含めるには、オプションの obsolete および inherit のブール値を指定します。各バージョンには timestamp フィールド（バージョンの日付）が含まれます。バージョンを変更するには、create_version、update_version、release_version、delete_version を参照してください
create_version	プロジェクトに新しいバージョンを作成し、作成されたバージョンオブジェクト（id、name、description、released、obsolete、timestamp）を返します。manage_project_threshold が必要です（デフォルト：manager）
update_version	既存のバージョンを更新します。渡したフィールドのみが変更されます（少なくとも1つ必須）。名前を変更すると、参照しているすべての課題の version／target_version／fixed_in_version が書き換えられます。manage_project_threshold が必要です（デフォルト：manager）
release_version	バージョンをリリース済みとしてマークし、日付を設定します（デフォルト：現在）。next_version を指定すると、同じ手順で後続バージョンを作成できます。manage_project_threshold が必要です（デフォルト：manager）
delete_version	バージョンを完全に削除します。元に戻せません。MantisBT は、参照しているすべての課題の version／target_version／fixed_in_version をクリアします。破壊的でない代替手段として、obsolete=true を指定した update_version の使用を推奨します。manage_project_threshold が必要です（デフォルト：manager）
get_project_categories	プロジェクトのカテゴリを取得します
get_project_users	プロジェクトのユーザーを取得します
find_project_member	名前、氏名、またはメールアドレスでプロジェクトメンバーを検索します（大文字と小文字を区別しない部分一致）。オプションの query と limit（デフォルトは10、最大100）を指定できます。キャッシュを優先します

セマンティック検索 (オプション)

完全一致のキーワード検索とは異なり、セマンティック検索ではクエリの背後にある 意味 を理解します。自然な言葉で尋ねると、表現が一致しなくても、検索エンジンが概念的に関連する課題を見つけます。

• 「パスワードをリセットした後にログインできない」 — 認証に関するエッジケースの課題を見つけます
• 「チェックアウトページのパフォーマンスの問題」 — 使用されている用語が正確に一致しなくても、関連する報告を表示します
• 「請求書一覧の重複項目」 — 「2回表示される」「レコードが重複している」などと説明された課題も見つけます

埋め込みモデル（約80 MB）は完全に オフライン で動作します。OpenAI のキーや外部 API は不要です。初回起動時に一度ダウンロードされ、ローカルにキャッシュされます。課題はサーバーの起動ごとに増分でインデックス化されます（再インデックス化されるのは新規および更新された課題のみです）。複数のクライアントセッションが同時にサーバーを起動した場合、共有インデックスを同期するのはそのうち1つだけです。モデルは初回使用時に読み込まれ、埋め込み処理が10分間行われないとアンロードされるため、アイドル状態のセッションがモデルのメモリ（サーバープロセスごとに約0.9 GB）を保持し続けることはありません。

MANTIS_SEARCH_ENABLED=true を設定して有効にします。

ツール	説明
search_issues	インデックス化されたすべての課題を自然言語で検索し、コサイン類似度スコア付きで上位N件を返します。オプションの select（カンマ区切りのフィールド名）を指定すると、各結果に要求した課題フィールドが追加されます。オプションの highlight（ブール値、デフォルトは false）を指定すると、各結果に highlights フィールドが追加されます。このフィールドには、summary と description からキーワードに一致した抜粋が含まれます（一致した用語は **太字** で表示されます）
rebuild_search_index	検索インデックスを作成または更新します。full: true を指定すると、インデックスをクリアして最初から再構築します
get_search_index_status	検索インデックスの現在の充填状況、つまりインデックス化された課題数と合計課題数、および最終同期のタイムスタンプを返します

どのバックエンドを選ぶべきですか？

	vectra (デフォルト)	sqlite-vec
依存関係	なし（純粋な JS）	ネイティブビルドツールが必要
インストール	同梱	npm install sqlite-vec better-sqlite3
最適な用途	約10,000件までの課題	10,000件以上の課題
パフォーマンス	ほとんどの環境で十分な速度	大規模なコーパスでより高速

まずは vectra を使用してください。インデックス化やクエリに明らかな時間がかかるようになったら、sqlite-vec に切り替えてください。

npm install sqlite-vec better-sqlite3
# then set MANTIS_SEARCH_BACKEND=sqlite-vec

メタデータとシステム

ツール	説明
get_issue_fields	list_issues の select パラメーターで有効なすべてのフィールド名を返します
get_metadata	コンパクトなメタデータの概要を取得します。プロジェクト数／タグ数と、プロジェクトごとのユーザー数／バージョン数／カテゴリ数を含みます。完全な配列が必要な場合は get_metadata_full を使用してください
get_metadata_full	メタデータキャッシュ全体を、整形を省いた JSON で返します（全プロジェクトの完全なフィールド、プロジェクトごとのユーザー／バージョン／カテゴリ、すべてのタグを含みます）
sync_metadata	メタデータキャッシュを更新します
list_filters	保存済みフィルターを一覧表示します
get_current_user	自分のユーザープロフィールを取得します
list_languages	利用可能な言語を一覧表示します
get_config	サーバー設定（ベース URL、キャッシュ TTL）を表示します
get_issue_enums	すべての課題列挙型フィールド（重大度、ステータス、優先度、解決状況、再現性）の有効な ID／名前の組み合わせを返します。正しい値を調べるため、create_issue／update_issue の前に使用してください。ローカライズされたインストール環境では、各項目に標準的な英語の API 名を示す canonical_name が含まれる場合があります
get_mantis_version	MantisBT のバージョンを取得し、更新を確認します
get_mcp_version	この mantisbt-mcp-server インスタンスのバージョンを返します

利用可能なリソース

MCP リソースは、クライアントがツールを呼び出さずに直接取得できる、URI で指定可能な読み取り専用データです。ツール、プロンプトと並ぶ、MCP の 3 つ目のプリミティブです。リソースへの対応は、ツールへの対応よりも MCP クライアントで広く実装されていないため、お使いのクライアントのドキュメントを確認してください。

リソース URI	説明
mantis://me	認証済み API ユーザーのプロフィール（ライブ取得）
mantis://projects	アクセス可能なすべての MantisBT プロジェクトをコンパクトな一覧で表示します（キャッシュを使用し、sync_metadata で更新）
mantis://projects/{id}	プロジェクトのフィールド、ユーザー、バージョン、カテゴリをまとめて取得するプロジェクトビューです。キャッシュを優先し、利用可能なすべてのプロジェクト URI を列挙するための一覧表示に対応しています
mantis://enums	すべての課題列挙型フィールド（重大度、優先度、ステータス、解決状況、再現性）の有効な値（ライブ取得）

利用可能なプロンプト

MCP プロンプトテンプレートは、構造化された入力を収集してから適切なツールを呼び出すよう LLM に指示する、会話のきっかけです。プロンプト自体はツールではなく、ガイド付きのワークフローを開始します。

プロンプト	必須引数	任意引数	説明
create-bug-report	project_id、category、summary、description	steps_to_reproduce、expected、actual、environment	構造化されたバグレポートの作成をガイドし、create_issue を呼び出します
create-feature-request	project_id、category、summary、description	use_case	機能リクエストの作成をガイドし、create_issue を呼び出します
summarize-issue	issue_id	–	get_issue で課題を取得し、簡潔な概要を返します
project-status	project_id	–	list_issues で課題を一覧表示し、重大度ごとにまとめたステータスレポートを作成します

HTTP モード

スタンドアロンサーバーとして使用する場合（リモート環境でのセットアップなど）。HTTP モードでは MCP_HTTP_TOKEN が必須です。この値が設定されていない場合、サーバーは起動を拒否します。

MCP_HTTP_TOKEN=secret MANTIS_BASE_URL=... MANTIS_API_KEY=... \
  TRANSPORT=http PORT=3456 node dist/index.js

# With 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

すべての /mcp リクエストで Authorization: Bearer <token> を送信する必要があります。HTTP 経由では、MANTIS_UPLOAD_DIR が設定されていない限り、upload_file の file_path は無効です。代わりに content（Base64）パラメーターを使用してください。

ヘルスチェック：GET http://localhost:3456/health（常に公開されており、トークンは不要です）

ドキュメント

• Cookbook — 登録済みのすべてのツールについて、コピーしてすぐに使えるパラメーター例を含む、ツール中心のレシピ
• 使用例 — 日常的なユースケース向けの自然言語プロンプト例（ツール名は不要です）

開発

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

ライセンス

MIT – LICENSE を参照してください

貢献

貢献を歓迎します。CONTRIBUTING.md をお読みください。 リポジトリ：codeberg.org/dpesch/mantisbt-mcp-server