redmine-local-mcp

Redmine REST API を MCP ツールとして公開するローカル STDIO サーバーです。 Codex CLI / GitHub Copilot CLI などの MCP クライアントから、Redmine のプロジェクトやチケットを参照できます。

方針

• Redmine は直接クラウド側へ公開せず、開発者 PC 上のローカル MCP サーバーから REST API に接続します。
• API キーは専用ユーザーの最小権限キーを使います。
• 初期状態では読み取り中心です。書き込み系の create_issue / add_issue_note は REDMINE_ENABLE_WRITE=true のときだけ動きます。

機能

• プロジェクト一覧の取得
• チケット検索、チケット詳細取得、自分の担当チケット取得
• 明示的に有効化した場合のみ、チケット作成とコメント追加

セットアップ

git clone https://github.com/<owner>/redmine-local-mcp.git
cd redmine-local-mcp
npm install
npm run build

.env.example を参考に、MCP クライアント側の環境変数として次の値を渡してください。 .env はローカル開発用で、Git にコミットしないでください。

REDMINE_URL=https://redmine.example.local
REDMINE_API_KEY=xxxxxxxxxxxxxxxx
REDMINE_ENABLE_WRITE=false

MCP クライアント設定

以下の例では、このリポジトリを /path/to/redmine-local-mcp に clone したものとして書いています。 実際の環境に合わせてパスを置き換えてください。

Codex CLI

[mcp_servers.redmine]
command = "node"
args = ["/path/to/redmine-local-mcp/dist/index.js"]
default_tools_approval_mode = "prompt"

[mcp_servers.redmine.env]
REDMINE_URL = "https://redmine.example.local"
REDMINE_API_KEY = "xxxxxxxxxxxxxxxx"
REDMINE_ENABLE_WRITE = "false"

GitHub Copilot CLI

copilot mcp add redmine \
  --env REDMINE_URL=https://redmine.example.local \
  --env REDMINE_API_KEY=xxxxxxxxxxxxxxxx \
  --env REDMINE_ENABLE_WRITE=false \
  -- node /path/to/redmine-local-mcp/dist/index.js

Agent Skill

Redmine MCP の使い方や安全ルールをまとめた Agent Skill を同梱しています。 このリポジトリでは Skill の原本だけを管理し、使う環境のユーザープロファイルへ手動でコピーします。

Skill 本体:

agent-skills/redmine-workflows/SKILL.md

GitHub Copilot の個人用 Skill として使う場合のコピー例:

New-Item -ItemType Directory -Force "$env:USERPROFILE\.copilot\skills\redmine-workflows"
Copy-Item -Recurse -Force .\agent-skills\redmine-workflows\* "$env:USERPROFILE\.copilot\skills\redmine-workflows\"

.agents 配下で Skill を管理する環境では、コピー先を次のように置き換えます。

New-Item -ItemType Directory -Force "$env:USERPROFILE\.agents\skills\redmine-workflows"
Copy-Item -Recurse -Force .\agent-skills\redmine-workflows\* "$env:USERPROFILE\.agents\skills\redmine-workflows\"

この Skill には API キーや Redmine URL は含めません。接続情報は MCP クライアント設定の環境変数で渡してください。

提供ツール

• list_projects: プロジェクト一覧を取得します。
• search_issues: チケットを検索します。
• get_issue: チケット詳細を取得します。
• get_my_issues: 自分に割り当てられたチケットを取得します。
• create_issue: チケットを作成します。REDMINE_ENABLE_WRITE=true が必要です。
• add_issue_note: チケットにコメントを追加します。REDMINE_ENABLE_WRITE=true が必要です。

設計メモ

設計判断や拡張時の注意点は docs/code-guide.md にまとめています。

主なファイル:

• src/index.ts: MCPツールを登録する入口です。
• src/redmineClient.ts: Redmine REST APIを呼び出す処理です。
• src/config.ts: 環境変数を読み込む処理です。
• tests/: 実Redmineへ接続せずに動作を確認するテストです。

書き込み系を有効にする

チケット作成やコメント追加を行う場合は、環境変数を次のように設定します。

REDMINE_ENABLE_WRITE=true

create_issue の最小入力例:

{
  "project_id": "sample-project",
  "subject": "ログイン画面のエラーを確認する",
  "description": "再現手順と期待結果を整理する。"
}

add_issue_note の入力例:

{
  "id": 1234,
  "notes": "調査を開始しました。再現条件を確認中です。"
}

開発

npm run typecheck
npm run build
npm test

テストは実 Redmine へ接続せず、HTTP 呼び出しをモックします。

セキュリティ

• REDMINE_API_KEY は専用ユーザーの最小権限キーを使ってください。
• .env や実 URL を含む MCP クライアント設定はコミットしないでください。
• 書き込みツールは REDMINE_ENABLE_WRITE=true を明示した場合だけ有効です。
• 脆弱性や秘密情報の混入を見つけた場合は、公開 issue ではなくリポジトリ管理者へ非公開で連絡してください。

公開前チェックリスト

• .env が Git 管理対象になっていないことを確認する。
• README 内の <owner> と /path/to/redmine-local-mcp を公開先に合わせる。
• Agent Skill に実 Redmine の URL、API キー、社内固有の非公開ルールが含まれていないことを確認する。
• 実 Redmine の URL、API キー、社内プロジェクト名が含まれていないことを確認する。
• npm run typecheck、npm run build、npm test が通ることを確認する。

ライセンス

MIT License