0
0

Delete article

Deleted articles cannot be recovered.

Draft of this article would be also deleted.

Are you sure you want to delete this article?

@mamono210(弍百獣 魔物)

macOS 版 Claude Desktop と Redmine を MC P連携する手順 | @onozaty/redmine-mcp-server を利用したローカル接続

0
Posted at

本記事では、macOS版Claude DesktopからRedmineへModel Context Protocol（MCP）を使って接続する方法を解説します。

MCPサーバーには、GitHubで公開されているonozaty/redmine-mcp-serverを使用します。

単に接続するだけではなく、APIキーの保護、ツール単位のアクセス制御、書き込み操作の制限まで扱います。

本記事は、GitHubのソースコードとnpmで公開されているバージョン1.3.0の実装を確認した内容に基づいています。個別のMacとRedmine環境での接続成功を報告するものではありません。

1. この記事の目的

Claude Desktopから、自然言語を使ってRedmineの情報を取得・操作できるようにします。

例えば、次のような用途です。

  • 最近更新されたチケットを取得する
  • チケットの説明やコメントを確認する
  • プロジェクトやバージョンを取得する
  • ロードマップの進捗を分析する
  • Wikiページを取得する
  • 必要に応じてチケットの作成や更新を行う

最初は読み取り専用で接続し、正常性を確認してから必要な書き込み機能だけを有効化します。

1.1 システム構成

macOS
┌───────────────────────────────┐
│                               │
│  Claude Desktop               │
│        │                      │
│        │ MCP / stdio          │
│        ▼                      │
│  @onozaty/redmine-mcp-server  │
│        │                      │
└────────│──────────────────────┘
         │
         │ HTTPS / REST API
         ▼
   Redmine Server

Claude Desktopが@onozaty/redmine-mcp-serverを子プロセスとして起動します。

MCPの通信には標準入力・標準出力を使うstdio方式を使用します。MCPサーバーがRedmine REST APIを呼び出してデータを取得します。

この構成では、OpenAI Secure MCP Tunnel、Tunnel ID、Runtime API Keyは必要ありません。

ただし、MacからRedmineサーバーへネットワーク接続できる必要があります。Redmineがプライベートネットワーク内にある場合は、VPNなど別途接続経路が必要です。

1.2 ChatGPT Web版との違い

項目 ChatGPT Web Mac Claude Desktop
MCP接続 Remote MCP / Tunnel ローカルstdio
MCP実行場所 PC・VMなど Mac
Tunnel Client 構成により必要 不要
MCP設定 ChatGPTアプリ設定 ローカルJSON設定
MCP起動 別途Runtime管理 Claude Desktopが起動
Macスリープの影響 MCP実行場所による ローカルMCPが停止・中断する可能性

なお、MCPサーバーをローカルで動かすことと、Claudeに渡したRedmineデータがMacの外へ送信されないことは別です。

Claudeで処理する情報については、利用中のサービスのデータ取り扱い設定も確認してください。

2. 必要なソフトウェア

2.1 Claude Desktop

macOS版Claude Desktopをインストールします。

公式サイト：

本記事では、Claude DesktopのローカルMCPサーバー設定機能を使用します。

Claude CodeのCLI設定とは異なるため、両者を混同しないようにしてください。

2.2 Node.js

@onozaty/redmine-mcp-serverはNode.jsを利用します。

Node.jsのLTS版を推奨します。

公式サイト：

ターミナルで次のコマンドを実行します。

node --version
npm --version
npx --version

続いて、npxの実行ファイルの場所を確認します。

command -v npx

Apple Silicon MacでHomebrewからNode.jsを導入した場合の例：

/opt/homebrew/bin/npx

Intel Macでの例：

/usr/local/bin/npx

ここに表示されたパスは、後でClaude Desktopの設定に使用します。

Node.jsをnvmなどで管理している場合は、異なるパスになります。

2.3 Redmine

Redmine側では次の準備が必要です。

  • REST APIが有効になっていること
  • Redmine APIアクセスキーが発行されていること
  • APIキーの所有ユーザーに対象プロジェクトの閲覧権限があること
  • MacからRedmineへ接続できること

書き込みも行う場合は、対象操作に必要なRedmine権限が追加で必要です。

3. Redmine REST APIを準備する

3.1 REST APIを有効化する

Redmineの管理者でログインします。

以下の画面を開きます。

管理
  └─ 設定
      └─ API
          └─ RESTによるWebサービスを有効にする

設定を有効にして保存します。

3.2 APIアクセスキーを取得する

MCPで使用するRedmineユーザーの個人設定画面を開きます。

個人設定
  └─ APIアクセスキー

APIアクセスキーを確認します。

本番利用では、管理者のAPIキーではなく、必要最小限の権限を持つRedmine連携専用ユーザーの使用を推奨します。

APIキーはパスワードと同様に扱います。

3.3 REST APIとの通信を確認する

MCPを設定する前に、MacからRedmine REST APIへ接続できることを確認します。

macOS標準のzshで以下を実行します。

export REDMINE_URL='https://redmine.example.com'

read -rs 'REDMINE_API_KEY?Redmine API Key: '
printf '\n'

printf 'X-Redmine-API-Key: %s\n' "$REDMINE_API_KEY" |
  curl -q -sS -o /dev/null \
    -w 'HTTP %{http_code}\n' \
    -H @- \
    "${REDMINE_URL}/projects.json?limit=1"

unset REDMINE_API_KEY

APIキーは画面に表示されず、curlのコマンドライン引数にも直接展開されません。

-H @-は標準入力からHTTPヘッダーを読み取る指定で、curl 7.55.0以降で利用できます。

-qは.curlrcなどのデフォルト設定ファイルを読み込まないための指定です。curlの最初のオプションとして配置する必要があります。

使用しているcurlのバージョンは次のコマンドで確認できます。

curl --version

HTTP 200が返れば、プロジェクト一覧を取得するリクエストは成功しています。

ただし、公開プロジェクトを取得できた場合、APIキーの有効性や非公開プロジェクトへのアクセス権限までは確認できません。

必要に応じて、閲覧権限が必要な既知のプロジェクトを対象に確認してください。

注意：/users/current.jsonは接続確認に使用しません。

Redmineのユーザー情報取得APIは、応答にAPIキーが含まれる場合があります。

接続確認を行うために、そのような秘密情報を取得する必要はありません。

4. Claude DesktopにMCPサーバーを設定する

4.1 設定ファイルを開く

Claude Desktopを起動します。

macOSのメニューバーから以下の順で開きます。

Claude
  └─ Settings
      └─ Developer
          └─ Edit Config

設定ファイルは通常、次の場所にあります。

~/Library/Application Support/Claude/claude_desktop_config.json

ターミナルから直接編集する場合は、次のコマンドを使えます。

open -a TextEdit \
  "$HOME/Library/Application Support/Claude/claude_desktop_config.json"

ファイルが存在しない場合は、Claude DesktopのEdit Config機能から作成するか、保存先ディレクトリを確認してから新規作成します。

4.2 MCPサーバーを登録する

claude_desktop_config.jsonに以下を記載します。

Apple Silicon MacでHomebrewを利用している場合の例です。

{
  "mcpServers": {
    "redmine": {
      "command": "/opt/homebrew/bin/npx",
      "args": [
        "-y",
        "@onozaty/redmine-mcp-server@1.3.0"
      ],
      "env": {
        "PATH": "/opt/homebrew/bin:/usr/local/bin:/usr/bin:/bin:/usr/sbin:/sbin",
        "REDMINE_URL": "https://redmine.example.com",
        "REDMINE_API_KEY": "YOUR_REDMINE_API_KEY",
        "REDMINE_MCP_READ_ONLY": "true",
        "REDMINE_MCP_TOOLS_DENY_PATTERN": "^(getCurrentUser|getMyAccount|getUser|downloadAttachmentToLocalFile|downloadThumbnailToLocalFile|delete.*|archive.*)$"
      }
    }
  }
}

REDMINE_URLとREDMINE_API_KEYを実際の環境に置き換えます。

commandには、先ほどcommand -v npxで確認したパスを指定してください。

PATHにはNode.jsの実行ファイルが格納されているディレクトリを含めます。

macOSでは、ターミナルから起動したコマンドと、GUIアプリから起動したコマンドで環境変数が異なる場合があります。そのため、実行ファイルの絶対パスとPATHを明示しています。

既にほかのMCPサーバーを登録している場合は、既存のmcpServersを消さず、redmineの設定だけを追加してください。

本記事では、**ソースコードと公開パッケージの実装を確認したバージョン1.3.0**を使用します。

@onozaty/redmine-mcp-server@1.3.0

バージョンを固定することで、意図しない更新によってMCPの動作や公開ツールが変化するリスクを減らせます。

ただし、初回取得時にはパッケージがダウンロード・実行されるため、バージョン固定だけでサプライチェーンのリスクを完全に排除できるわけではありません。

注意：この基本設定例ではAPIキーがJSONファイルに平文で保存されます。

接続検証用の簡易構成として紹介していますが、継続運用では第8章のmacOSキーチェーン方式を推奨します。

一時的に平文設定を使用する場合でも、ファイルのアクセス権限を制限します。

chmod 600 \
  "$HOME/Library/Application Support/Claude/claude_desktop_config.json"

4.3 読み取り専用モードの注意点

REDMINE_MCP_READ_ONLYは、設定値が厳密に小文字の文字列"true"と一致した場合だけ有効になります。

リポジトリのsrc/config.tsでは、次のように判定されています。

const readOnlyMode =
  process.env.REDMINE_MCP_READ_ONLY === "true";

設定値の違いによる挙動は次のとおりです。

設定値 読み取り専用
"true" 有効
"TRUE" 無効
"True" 無効
"1" 無効
"false" 無効
未設定 無効

"TRUE"や"1"を指定すると、読み取り専用にはならず、ほかのツール公開制限に一致しない書き込み系ツールが公開されます。

JSONの設定例では、必ず次のように指定します。

"REDMINE_MCP_READ_ONLY": "true"

設定変更後は、起動ログで読み取り専用モードが有効になっていることも確認してください。

4.4 読み取り専用でも秘密情報を返すツールが残る

ここは特に重要です。

@onozaty/redmine-mcp-serverの読み取り専用モードは、サーバーがWRITEとして分類したツールを無効化する仕組みです。

しかし、getCurrentUserとgetMyAccountはREAD_ONLYとして分類されています。

これらはRedmineのユーザー情報を返すツールであり、APIの応答にapi_keyが含まれる可能性があります。

また、getUserも対象ユーザーや権限によってAPIキーを返す可能性があります。

ツール 分類 注意点
getCurrentUser READ_ONLY APIキーを返す可能性
getMyAccount READ_ONLY APIキーを返す可能性
getUser READ_ONLY 対象や権限によってAPIキーを返す可能性

REDMINE_MCP_READ_ONLY=trueだけでは、これらのツールを無効化できません。

したがって、本記事では次のツールを明示的に除外します。

"REDMINE_MCP_TOOLS_DENY_PATTERN": "^(getCurrentUser|getMyAccount|getUser)$"

秘密情報が応答に含まれる可能性のあるツールは、プロンプトだけで実行を禁止するのではなく、MCPサーバー側で公開対象から除外する方が確実です。

この設定は、確認された3ツールに対する対策です。ほかのAPIの応答やRedmineのチケット本文などに機密情報が含まれる可能性まで排除するものではありません。

4.5 読み取り専用でもMacへファイルを書き込むツールが残る

もう一つ注意が必要です。

次の2つのツールも、MCPサーバー内部ではREAD_ONLYとして分類されています。

downloadAttachmentToLocalFile
downloadThumbnailToLocalFile

これらのツールはRedmineから添付ファイルやサムネイルをダウンロードします。

Redmine上のデータは変更しませんが、Mac側には副作用があります。

実装では、出力先ディレクトリが存在しない場合にディレクトリを作成し、取得したファイルを保存しています。

Claude Desktop
      │
      ▼
downloadAttachmentToLocalFile
      │
      ▼
Redmineからファイル取得
      │
      ▼
Macのディレクトリを作成
      │
      ▼
Macへファイルを書き込み

出力先はoutputDirで指定でき、未指定の場合はOSの一時ディレクトリが使われます。

また、MCPサーバーはこれらのツールにreadOnlyHint: trueを設定して公開しています。

この注釈は、クライアントがツールを読み取り操作として扱う判断材料になります。

そのため、Claude Desktop側の許可設定によっては、個別の承認を求めずに実行される可能性があります。

readOnlyHintは、Macのファイルシステムに一切変更を加えないことを保証するものではありません。

本記事では、ローカルファイルのダウンロードが不要な前提で、これらのツールも除外します。

実際の初期設定では、秘密情報を返すツール、ローカルファイルへ書き込むツール、削除・アーカイブ系ツールをまとめて除外します。

"REDMINE_MCP_TOOLS_DENY_PATTERN": "^(getCurrentUser|getMyAccount|getUser|downloadAttachmentToLocalFile|downloadThumbnailToLocalFile|delete.*|archive.*)$"

これが第4.2節で採用した設定です。

5. Claude Desktopを再起動する

設定ファイルを保存したら、Claude Desktopを完全に終了します。

macOSではCommand + Qで終了し、再起動します。

単にウィンドウを閉じるだけでは、アプリ本体が終了していない場合があります。

再起動すると、Claude Desktopが設定に従ってMCPサーバーを起動します。

Claude Desktop起動
       │
       ▼
claude_desktop_config.json 読込
       │
       ▼
npx 実行
       │
       ▼
@onozaty/redmine-mcp-server 起動
       │
       ▼
公開対象ツールの絞り込み
       │
       ▼
MCPツール登録
       │
       ▼
Claude Desktopから利用可能

基本的には、MCPサーバーをターミナルから常時起動しておく必要はありません。

6. MCP接続を確認する

6.1 接続状態を確認する

Claude Desktopのチャット入力欄から、以下の順で開きます。

+
  └─ Connectors
      └─ Manage connectors
          └─ redmine

RedmineのMCPサーバーと利用可能なツールが表示されるか確認します。

Developer設定からも、MCPサーバーの接続状態やログを確認できます。

ツールが表示されない場合は、第9章のトラブルシューティングを参照してください。

6.2 最初の読み取りテスト

まず、Redmineに変更を加えない簡単な問い合わせを実行します。

Redmine MCPのgetProjectsを使用して、
アクセスできるプロジェクトを5件取得してください。

表示するのはプロジェクト名と識別子だけにしてください。
Redmineへの書き込みは行わないでください。

続いて、チケットを取得します。

Redmine MCPを使用して、
最近更新されたチケットを5件取得してください。

チケット番号、件名、プロジェクト、
ステータス、更新日時を表示してください。

正常に取得できれば、少なくとも以下の経路が利用できています。

Claude Desktop
      │
      ▼
MCP Tool Call
      │
      ▼
Redmine MCP Server
      │
      ▼
Redmine REST API
      │
      ▼
Redmine

MCPサーバーの起動に成功しただけでは、Redmineとの通信が成功したことにはなりません。

実際のツール呼び出しが成功し、期待するRedmineデータを取得できたところまで確認します。

6.3 Wikiとバージョン情報を取得する

接続確認後は、Wikiやバージョンも取得できます。

Redmine MCPを利用して、
指定したプロジェクトのWikiページ一覧を取得してください。

Redmine MCPを利用して、
指定したプロジェクトのバージョン一覧を取得してください。

なお、ロードマップの進捗率を計算する場合、バージョン情報だけでなく、関連チケットのステータスや進捗率などを組み合わせる必要がある場合があります。

7. 書き込みを有効にする

読み取り確認が成功し、書き込み権限の設計を確認したら、必要に応じて更新系ツールを有効化します。

ただし、書き込みを有効にする際には、DenyパターンだけではなくAllowパターンによる許可リストを推奨します。

7.1 Denyパターンだけでは不十分

例えば、次の設定を使用したとします。

"REDMINE_MCP_TOOLS_DENY_PATTERN": "^(delete|archive)"

この設定では、名前がdeleteまたはarchiveで始まるツールを除外できます。

しかし、それ以外にもRedmineの状態を変更できるツールが存在します。

具体例：

ツール 操作
closeProject プロジェクトをクローズ
removeWatcher ウォッチャーを削除
removeRelatedIssue 関連付けを削除
updateJournal 既存コメントを更新
updateMyAccount アカウント情報を更新
createUser ユーザーを作成

これらは^(delete|archive)には一致しません。

したがって、単純なDenyパターンだけで危険な操作を網羅的に防ぐことはできません。

7.2 Allowパターンで必要なツールだけを公開する

@onozaty/redmine-mcp-serverには次の環境変数があります。

REDMINE_MCP_TOOLS_ALLOW_PATTERN
REDMINE_MCP_TOOLS_DENY_PATTERN

Allowパターンは、一致した名前のツールだけを公開します。

Denyパターンは、一致した名前のツールを除外します。

両方を設定した場合は、Denyが優先されます。

例えば、チケットの取得・作成・更新、プロジェクト・Wiki・バージョンの取得に加え、更新に必要な各種IDも取得する場合は、次の設定にします。

既存のenv内の設定を変更してください。

{
  "REDMINE_MCP_READ_ONLY": "false",
  "REDMINE_MCP_TOOLS_ALLOW_PATTERN": "^(getProjects|getProject|getIssues|getIssue|getIssueStatuses|getTrackers|getIssuePriorities|getMemberships|getVersionsByProject|getVersions|getWikiPages|getWikiPage|getWikiPageByVersion|getIssueRelations|search|createIssue|updateIssue)$",
  "REDMINE_MCP_TOOLS_DENY_PATTERN": "^(getCurrentUser|getMyAccount|getUser|downloadAttachmentToLocalFile|downloadThumbnailToLocalFile|delete.*|archive.*)$"
}

上記はenvに追加・置換する項目を示した抜粋です。既存のREDMINE_URLやREDMINE_API_KEYはそのまま維持します。

許可するツールは以下のとおりです。

分類 ツール 用途
プロジェクト getProjects, getProject プロジェクトの取得
チケット getIssues, getIssue チケットの取得
ステータス getIssueStatuses ステータスIDの確認
トラッカー getTrackers トラッカーIDの確認
優先度 getIssuePriorities 優先度IDの確認
メンバー getMemberships プロジェクトメンバーと担当者候補の確認
バージョン getVersionsByProject, getVersions バージョンの取得
Wiki getWikiPages, getWikiPage, getWikiPageByVersion Wikiの取得と過去版の確認
関連チケット getIssueRelations チケット間の関連を取得
検索 search Redmine内の検索
チケット作成 createIssue チケットを作成
チケット更新 updateIssue チケットを更新

書き込み系では、createIssueとupdateIssueだけを公開する構成です。

それ以外の書き込みツールは、許可リストにないため公開されません。

IDは推測せず、取得したRedmineの情報から判断します。

例えば、ステータスを変更する場合はgetIssueStatusesで現在利用可能なステータスとIDを取得します。

担当者を指定する場合は、getMembershipsで対象プロジェクトのメンバーを確認します。ただし、グループ担当など、getMembershipsだけでは十分な情報を取得できない場合もあります。

必要なIDを確認できない場合は、推測して更新せず、追加の読み取り方法や人間への確認を検討します。

書き込み版では読み取り範囲も変わる

Allowパターンは、書き込みツールだけでなく、読み取りツールにも適用されます。

そのため、読み取り専用モードで利用できていたツールでも、Allowパターンに含まれていなければ、書き込みモードへ切り替えた後は使えなくなります。

今回の例では、search、getIssueRelations、getWikiPageByVersionなどを明示的に追加しています。

一方、getTimeEntries、getQueries、getAttachmentなどは追加していません。

これらが必要になった場合は、利用目的と応答内容を確認したうえで、許可リストに追加します。

つまり、Allowパターンを使う場合は、書き込みだけでなく、業務に必要な読み取り操作も含めて設計する必要があります。

Denyパターンの重複指定について

今回のAllowパターンにはdeleteやarchiveで始まるツールが含まれていません。

そのため、Denyパターンのdelete.*|archive.*は、現在の設定では念のための重複指定です。

ただし、将来Allowパターンを変更した場合に備えて残しています。

本記事では、読み取り専用・書き込み・キーチェーン方式の各設定で、同じDenyパターンを使用します。

なお、このDenyパターンだけで削除・変更系の操作を網羅できるわけではありません。安全性の中心は、必要なツールだけを列挙するAllowパターンとRedmine側の権限制限です。

7.3 書き込み時の安全対策

Redmineへの書き込みには、人間による操作承認を組み合わせることを推奨します。

例えば、次のルールです。

  • 書き込み前に対象と変更内容を提示する
  • 人間の明示的な承認後に実行する
  • 削除操作は原則として許可しない
  • 更新後はRedmineを読み戻して結果を確認する
  • 通信切断などで結果が不明な場合は、無条件で同じ操作を再実行しない
  • 専用の更新経路が定められた保護フィールドは、汎用MCPから変更しない

Claude Desktopのツール実行許可機能だけに依存せず、Redmine側のロールと権限でも操作範囲を制限することが重要です。

また、updateIssue自体には多数の更新対象フィールドがあります。

ツール名による制限だけでは、個別フィールドの保護はできません。

専用の更新経路が定められているフィールドを汎用MCPから変更させたくない場合は、別のAPIキー・Redmineロール・専用writerなどによる制御が必要です。

8. macOSキーチェーンを利用してAPIキーを保護する

ここまでは構築を分かりやすくするため、JSONファイルにAPIキーを書く方法を紹介しました。

しかし、継続利用する場合はAPIキーをmacOSキーチェーンへ保存する方式を推奨します。

この方法では、Claude DesktopのJSON設定ファイルからAPIキーの平文を除去できます。

8.1 APIキーをキーチェーンへ登録する

ターミナルで実行します。

security add-generic-password \
  -U \
  -a "redmine-mcp" \
  -s "claude-redmine-api-key" \
  -w

APIキーを対話的に入力します。

-wを最後に置くことで、キーをコマンドライン引数に直接書く必要がなくなります。

-Uは同じ項目が存在する場合の更新を許可する指定です。

8.2 起動用スクリプトを作成する

次のディレクトリを作成します。

mkdir -p "$HOME/.local/bin"

ファイルを作成します。

nano "$HOME/.local/bin/claude-redmine-mcp"

内容は以下のとおりです。

#!/bin/zsh

set -euo pipefail

export PATH="/opt/homebrew/bin:/usr/local/bin:/usr/bin:/bin:/usr/sbin:/sbin"

export REDMINE_URL="https://redmine.example.com"

# 読み取り専用モードを有効化
export REDMINE_MCP_READ_ONLY="true"

# 読み取り専用ではAllowパターンを使用しない
unset REDMINE_MCP_TOOLS_ALLOW_PATTERN

# 秘密情報を返すツール、
# ローカルファイルへ書き込むツール、
# 削除・アーカイブ系ツールを除外
export REDMINE_MCP_TOOLS_DENY_PATTERN='^(getCurrentUser|getMyAccount|getUser|downloadAttachmentToLocalFile|downloadThumbnailToLocalFile|delete.*|archive.*)$'

# macOSキーチェーンからAPIキーを取得
api_key="$(
  /usr/bin/security find-generic-password \
    -a "redmine-mcp" \
    -s "claude-redmine-api-key" \
    -w
)" || exit 1

[[ -n "$api_key" ]] || exit 1

export REDMINE_API_KEY="$api_key"
unset api_key

# バージョンを固定してMCPサーバーを起動
exec "$(command -v npx)" \
  -y "@onozaty/redmine-mcp-server@1.3.0"

REDMINE_URLを実際の接続先に変更してください。

Node.jsの導入場所が異なる場合は、PATHも調整します。

このスクリプトでは、読み取り専用モードに加えて、第4章で説明したツールの除外設定も適用しています。

Denyパターンは第4.2節のJSON設定と同じです。

実行権限を付与します。

chmod 700 "$HOME/.local/bin/claude-redmine-mcp"

8.3 Claude Desktopの設定を変更する

設定を以下のように変更します。

{
  "mcpServers": {
    "redmine": {
      "command": "/Users/yourname/.local/bin/claude-redmine-mcp",
      "args": []
    }
  }
}

yournameを実際のmacOSユーザー名に置き換えます。

JSONのcommandには~ではなく絶対パスを指定してください。

この構成では起動スクリプトがキーチェーンからAPIキーを取得し、環境変数としてMCPサーバーに渡します。

初回起動時にはmacOSがキーチェーンへのアクセス許可を求める場合があります。

キーチェーン方式でも、MCPサーバーの実行中はAPIキーが環境変数に存在します。

秘密情報へのアクセスを完全に防止する方式ではありませんが、JSONファイルへの平文保存を避けられます。

8.4 キーチェーン方式で書き込みを有効にする場合

第7章のAllowパターンを利用する場合、起動スクリプト内の設定を変更します。

読み取り専用設定を次のように変更します。

export REDMINE_MCP_READ_ONLY="false"

続いて、第8.2節のunset REDMINE_MCP_TOOLS_ALLOW_PATTERNを削除し、次の設定に置き換えます。

export REDMINE_MCP_TOOLS_ALLOW_PATTERN='^(getProjects|getProject|getIssues|getIssue|getIssueStatuses|getTrackers|getIssuePriorities|getMemberships|getVersionsByProject|getVersions|getWikiPages|getWikiPage|getWikiPageByVersion|getIssueRelations|search|createIssue|updateIssue)$'

Denyパターンは変更せず、第8.2節の設定をそのまま維持します。

export REDMINE_MCP_TOOLS_DENY_PATTERN='^(getCurrentUser|getMyAccount|getUser|downloadAttachmentToLocalFile|downloadThumbnailToLocalFile|delete.*|archive.*)$'

これにより、第7.2節のJSON設定と同じツール制限になります。

設定変更後はClaude Desktopを完全に再起動し、公開ツール一覧を確認します。

9. トラブルシューティング

9.1 Claude DesktopにMCPサーバーが表示されない

まず、設定ファイルの構文を確認します。

python3 -m json.tool \
  "$HOME/Library/Application Support/Claude/claude_desktop_config.json" \
  > /dev/null

構文エラーがなければ、通常は何も表示されません。

その後、npxのパスとPATHを確認します。

9.2 ログを確認する

Claude DesktopのMCP関連ログは通常、次のディレクトリに保存されます。

~/Library/Logs/Claude/

確認例：

ls -l "$HOME/Library/Logs/Claude/"

MCPログを調査する場合：

tail -n 50 \
  "$HOME/Library/Logs/Claude/mcp.log"

Redmine MCPサーバー固有のログが存在する場合：

tail -n 50 \
  "$HOME/Library/Logs/Claude/mcp-server-redmine.log"

ログファイル名は設定したMCPサーバー名に対応します。

ログには機密情報が含まれる可能性があるため、他人へ共有する前に必ず内容を確認してください。

9.3 読み取り専用なのに書き込みツールが表示される

まず、設定値を確認します。

"REDMINE_MCP_READ_ONLY": "true"

"TRUE"や"1"になっていないか確認してください。

また、変更後にClaude Desktopを完全に再起動したか確認します。

読み取り専用として認識されると、起動ログに次のような内容が表示されます。

Read-only mode: write operations disabled

さらに、同じログにある以下の行も確認します。

Available tools: N operations
Disabled tools: M operations

Nは公開されたツール数、Mは無効化されたツール数を表します。実際には数値が表示されます。

Allow/Denyパターンを設定すると、利用可能なツール数が変わります。

ログには有効になったパターンも出力されるため、設定した正規表現が反映されているかを確認できます。

ただし、ツール数だけでは、特定の危険なツールが除外されていることを保証できません。

Claude Desktopのツール一覧も確認し、getCurrentUser、getMyAccount、getUser、downloadAttachmentToLocalFile、downloadThumbnailToLocalFileが公開されていないことを確認してください。

9.4 Node.jsが見つからない

典型的な原因は、GUIアプリとターミナルの環境変数の違いです。

次を確認します。

command -v node
command -v npx

取得した実行ファイルの場所をcommandやPATHに反映してください。

9.5 Redmineへ接続できない

以下の順番で確認します。

レイヤー 確認内容
Mac Redmineへネットワーク接続できるか
Redmine REST API APIが有効か
認証 APIキーが正しいか
Redmine権限 対象プロジェクトを閲覧できるか
Node.js nodeとnpxが起動できるか
MCP サーバープロセスが正常起動するか
Claude Desktop MCPツールを認識しているか
実行 ツール呼び出しが成功するか

@onozaty/redmine-mcp-serverはstdio方式のMCPサーバーです。

単体で実行しても、通常のHTTPサーバーのようにlocalhostの待受ポートが表示されることはありません。

また、MCPプロセスの起動ログにツール数が表示されても、Redmine REST APIへの通信成功を意味するわけではありません。

9.6 ツールが表示されるが実行できない

MCPの接続自体は成立していても、以下の原因が考えられます。

  • APIキーの権限不足
  • Redmine側のアクセス制限
  • REST APIの認証エラー
  • MacからRedmineへの通信障害
  • APIとMCPサーバーの応答形式の不整合
  • Allow/Denyパターンによる対象ツールの除外

この場合は、Claude DesktopのログとRedmine側のログを組み合わせて調査します。

10. セキュリティ上の注意

10.1 APIキーとRedmineユーザー

@onozaty/redmine-mcp-serverは、設定されたRedmine APIキーを利用してREST APIを呼び出します。

同じキーを複数のクライアントで共用すると、Redmine側では同じユーザーによる操作として記録されます。

そのため、本番利用では用途に応じてAPIキーとRedmineユーザーを分離する設計が重要です。

10.2 読み取り専用は副作用ゼロを意味しない

読み取り専用モードは、Redmineに変更を加えるツールを制限するための機能です。

しかし、MCPサーバーが読み取りとして分類したツールの中には、秘密情報を返す可能性があるものや、ローカルファイルを作成するものが含まれています。

そのため、ツールの分類だけでなく、実際の動作や応答内容も確認する必要があります。

特に次の違いを意識してください。

観点 確認事項
Redmineの変更 チケットやWikiを書き換えるか
Macの変更 ファイルやディレクトリを作るか
秘密情報 APIキーなどを返す可能性があるか
ツールの注釈 readOnlyHintが実動作と整合しているか
実行権限 Claude Desktopが承認なしで実行し得るか

10.3 MCPツールの公開範囲

MCPのツール公開制御では、Allow/Denyパターンを適切に使用します。

読み取り専用の場合でも、秘密情報やローカルファイルへの副作用があるツールは必要に応じて除外します。

書き込みを有効にする場合は、許可リスト方式を基本とします。

ただし、許可したツールが何を実行できるかは、ツール名だけでは判断できません。

例えばupdateIssueが許可されている場合、その内部で変更可能なRedmineフィールドについても考慮する必要があります。

10.4 MCPサーバーのバージョン管理

継続運用では、動作を検証したパッケージバージョンを固定することを推奨します。

本記事では、ソースコードを確認した1.3.0を指定しています。

npx -y @onozaty/redmine-mcp-server@1.3.0

新しいバージョンへ更新する場合は、公開ツール、環境変数、読み取り専用の分類、セキュリティ上の変更点を確認してから切り替えます。

特に、ツールが新たに追加された場合、既存のDenyパターンでは除外されない可能性があります。

Allowパターンによる許可リストを使用していれば、新しいツールが意図せず公開されるリスクを減らせます。

10.5 ローカルPCのスリープ

この構成ではMCPサーバーがMac上で実行されます。

Macがスリープすると、ローカルMCP処理やRedmineへの接続が中断される可能性があります。

Mac版Claude DesktopのMCP連携は、Macから対話的にRedmineを操作する用途に適していますが、24時間稼働するAI Agentの実行基盤とは異なります。

PCから独立して継続処理を実行する場合は、GCEなどのサーバー上に常駐するRunnerや、スケジューラーを備えた別の実行基盤を検討します。

11. まとめ

macOS版Claude Desktopは、ローカルMCPサーバーを直接起動できます。

そのため、ChatGPT Web版で利用していたSecure MCP Tunnelなどの構成は必要ありません。

最も基本的な構成は以下のとおりです。

Claude Desktop
   ↓
claude_desktop_config.json
   ↓
npx
   ↓
@onozaty/redmine-mcp-server
   ↓
Redmine REST API
   ↓
Redmine

ただし、読み取り専用モードだけでは十分な安全性を確保できるとは限りません。

今回のMCPサーバーでは、読み取りとして分類されたツールの中にも、APIキーを返す可能性があるものやMacへファイルを書き込むものが存在します。

そのため、本記事では次の方針を採用しました。

  1. 読み取り専用モードを厳密に"true"で指定する
  2. 秘密情報を返す可能性があるツールを除外する
  3. ローカルファイルへ書き込むツールを除外する
  4. 書き込み時はAllowパターンで利用可能なツールを限定する
  5. 更新に必要なIDはRedmineから取得し、推測しない
  6. APIキーは可能な限りmacOSキーチェーンで管理する
  7. MCPサーバーのバージョンを固定する
  8. 書き込み操作には人間の承認と変更後の検証を組み合わせる

これらを組み合わせることで、Claude DesktopとRedmineの連携を、より管理しやすい構成で運用できます。

参考資料

MCPサーバー

Claude Desktop / MCP公式ドキュメント

設定ファイルの場所、Edit Config、MCPログのファイル名については、MCP公式ドキュメントを主要な参照先としています。

Redmine

macOS

0
0
0

Register as a new user and use Qiita more conveniently

  1. You get articles that match your needs
  2. You can efficiently read back useful information
  3. You can use dark theme
What you can do with signing up
Sign upLogin
0
0

Delete article

Deleted articles cannot be recovered.

Draft of this article would be also deleted.

Are you sure you want to delete this article?