redmine-mcp-connector

Redmine MCP サーバー

stdio ベースのModel Context Protocolサーバーで、Redmine インスタンスをREST API（*.json エンドポイント）経由で操作します。別個の Node.js プロセスとして実行されるため、Redmine の Rails アプリに変更を加える必要はありません。

要件

• Node.js 20+
• API アクセスキーを持つ Redmine ユーザー（マイアカウント → API アクセスキーを表示）
• このプロセスから Redmine の REDMINE_BASE_URL へのネットワークアクセス

インストール

通常の使用ではインストールは不要です。コーディングエージェントが必要に応じて npx 経由で起動します。

npx -y redmine-mcp-connector

Claude Desktop、Claude Code、Cursor、Windsurf、Cline、VS Code、Zed、その他の MCP クライアント向けの詳しいセットアップ手順と、ローカルビルドおよび Docker の代替方法については、CONNECTING.md を参照してください。

サーバー自体を開発するには、このリポジトリをクローンしてください。

npm install
npm run build

設定

環境変数（.env.example を参照）：

変数	必須	説明
REDMINE_BASE_URL	はい	ベース URL。例：https://redmine.example.com（末尾のスラッシュなし）
REDMINE_API_KEY	はい	X-Redmine-API-Key の値
REDMINE_IMPERSONATE_USER	いいえ	X-Redmine-Switch-User を設定します（Redmine では管理者のみ使用可能）
REDMINE_READONLY	いいえ	true / 1 の場合、変更を伴うすべての HTTP メソッドをブロックします
REDMINE_ALLOW_RAW_REQUEST	いいえ	true / 1 の場合、回避用ツール redmine_request を登録します
REDMINE_HTTP_TIMEOUT_MS	いいえ	デフォルトは 15000 です
REDMINE_MAX_PAGES	いいえ	リストツールで fetch_all を使用する際の最大ページ数（デフォルトは 20）
REDMINE_MAX_DOWNLOAD_BYTES	いいえ	redmine_attachment_download の上限（デフォルトは 5 MiB）

実行

REDMINE_BASE_URL=https://your-redmine.example.com REDMINE_API_KEY=secret npm start
# or during development:
REDMINE_BASE_URL=... REDMINE_API_KEY=... npm run dev

コーディングエージェントへの接続

クライアントごとの詳しい手順（Claude Desktop、Claude Code、Cursor、Windsurf、Cline、VS Code、Zed、および一般的な MCP クライアント）は CONNECTING.md にあります。簡単な例（Claude Desktop／Cursor／Windsurf では共通の形式です）：

{
  "mcpServers": {
    "redmine": {
      "command": "npx",
      "args": ["-y", "redmine-mcp-connector"],
      "env": {
        "REDMINE_BASE_URL": "https://redmine.example.com",
        "REDMINE_API_KEY": "your_api_key_here"
      }
    }
  }
}

MCP リソース（読み取り専用）

URI	説明
redmine://projects	GET /projects.json（最初の 100 件）
redmine://me	GET /users/current.json
redmine://me/issues	GET /issues.json?assigned_to_id=me（上限 100 件）
redmine://projects/{id}	GET /projects/:id.json

ツールの概要

命名規則：redmine_<resource>_<action>。

チケット： redmine_issues_list、redmine_issue_get、redmine_issue_create、redmine_issue_update、redmine_issue_add_comment、redmine_issue_delete（confirm: true が必要）、ウォッチャーの追加／削除、関連の一覧表示／追加／削除。

プロジェクト： redmine_projects_list、redmine_project_get、作成／更新／アーカイブ／アーカイブ解除／削除（削除には confirm が必要）。

ユーザー： redmine_current_user、redmine_users_list、redmine_user_get、作成／更新／削除（削除には confirm が必要）。

作業時間： 一覧表示／取得／作成／更新／削除（削除には confirm が必要）。

ニュース： 一覧表示／取得／作成／更新／削除（削除には confirm が必要）。

Wiki： ページの一覧表示／取得／作成／更新（PUT）／削除（confirm が必要）。

バージョンとカテゴリ： バージョンの CRUD（削除には confirm が必要）、チケットカテゴリの CRUD（削除には confirm が必要）。

クエリとメタデータ： redmine_queries_list、redmine_enumerations_list、redmine_trackers_list、redmine_issue_statuses_list、redmine_roles_list、redmine_role_get、redmine_custom_fields_list。

グループ（読み取り専用）： redmine_groups_list、redmine_group_get。

メンバーシップ： 一覧表示／作成／更新／削除（削除には confirm が必要）。

添付ファイルと検索： redmine_search、添付ファイルの取得／更新／削除／アップロード／ダウンロード（ダウンロード結果は base64 形式で、サイズ上限があります）。

リポジトリ（標準の Redmine REST API では制限あり）： redmine_repository_revision_link_issue、redmine_repository_revision_unlink_issue（confirm が必要）。JSON 経由でのリポジトリ／リビジョンの一覧表示は、Redmine コアでは公開されていません。有効にしている場合は redmine_request を使用するか、プラグインを利用してください。

回避手段： redmine_request — REDMINE_ALLOW_RAW_REQUEST=true の場合のみ使用できます。DELETE には confirm: true が必要です。

安全性

• 破壊的なツールでは、記載されている場合、明示的に confirm: true を指定する必要があります。
• 読み取り専用でデプロイする場合は、REDMINE_READONLY=true を設定してください。
• このサーバーが API キーをログに記録することはありません。

Docker

ローカルイメージをビルドします。

docker build -t redmine-mcp-server:local .

実行します（stdio MCP サーバー）。

docker run --rm -i   -e REDMINE_BASE_URL="https://redmine.example.com"   -e REDMINE_API_KEY="your_api_key_here"   redmine-mcp-server:local

MCP 設定でこのイメージを使用します。

{
  "mcpServers": {
    "redmine": {
      "command": "docker",
      "args": [
        "run", "--rm", "-i",
        "-e", "REDMINE_BASE_URL",
        "-e", "REDMINE_API_KEY",
        "docker.io/<docker-user>/redmine-mcp-server:latest"
      ],
      "env": {
        "REDMINE_BASE_URL": "https://redmine.example.com",
        "REDMINE_API_KEY": "your_api_key_here"
      }
    }
  }
}

Docker Hub Catalog への公開

1. ログインします。

docker login

2. buildx ビルダーを作成して使用します（初回のみ）。

docker buildx create --name redmine-mcp-builder --use --bootstrap

3. マルチアーキテクチャイメージをビルドしてプッシュします。

export IMAGE=docker.io/<docker-user>/redmine-mcp-server
export TAG=1.0.0

docker buildx build   --platform linux/amd64,linux/arm64   -t $IMAGE:$TAG   -t $IMAGE:latest   --push .

4. Docker Hub で、リポジトリの説明にこの README の内容を設定し、Catalog で見つけられるように公開に設定します。

開発

npm run lint
npm test

コントリビューション

コントリビューションを歓迎します。

• クライアントのセットアップ手順について詳しくは、CONNECTING.md をご覧ください。
• ローカル環境のセットアップ、コーディングの指針、PR のワークフローについては、CONTRIBUTING.md をお読みください。
• 敬意を持ち、誰もが参加できるコラボレーションを維持するため、CODE_OF_CONDUCT.md に従ってください。
• ヘルプを受けられる窓口や、記載すべき詳細については、SUPPORT.md をご利用ください。
• 脆弱性は、SECURITY.md に従って非公開で報告してください。
• 公開配布用テンプレート（Docker ＋ MCP ディレクトリ）については、REGISTRY_PUBLISHING.md をご覧ください。

ライセンス

GPL-2.0-or-later（Redmine と同じ系統です）。