mcp-redmine

Model Context Protocol サーバーであり、Claude（Desktop または Code）— またはその他の MCP クライアント — を REST API 経由で Redmine インスタンスに接続します。

実質的に Redmine の安定版 REST API 全体をカバーする 73 のツールを提供します：チケット、関連、プロジェクト、メンバーシップ、バージョン、カテゴリ、ユーザー、グループ、ロール、Wiki、工数管理、添付ファイル、プロジェクトファイル、ニュース、検索。エージェントを Redmine プロジェクトに向けるだけで、自然な会話を通じてチケットの読み取り・管理、工数の記録、Wiki ページの編集、ユーザー管理を実行できます。

特徴

• チケットの読み取り/書き込みを完全カバー：一括更新、関連、ウォッチャー、コメントを含む。

• プロジェクト管理：プロジェクトの作成/更新/アーカイブ、メンバー、バージョン、カテゴリの管理。

• ユーザーおよびグループ管理。「ユーザー削除」や「プロジェクト削除」のツールは意図的に含めていません — セキュリティ を参照。

• Wiki：ネストされたページとファイル添付を含む。

• 工数管理、添付ファイル、プロジェクトファイル、ニュース、全文検索。

• 読みやすいエラー：すべての失敗は Redmine 自身のバリデーション応答から抽出された明確な文章として返され、生のスタックトレースではありません。

• 実行するものは不要：MCP クライアントと stdio で通信する単一の Python プロセス — データベースも、ホストするサーバーも、Docker も不要です。

Related MCP server: redmine-mcp

前提条件

• Python 3.10+

• REST API が有効な Redmine インスタンス：

  1. Redmine で 管理 → 設定 → API に移動し、「REST Web サービスを有効にする」をオンにします（まだの場合）。

  2. マイアカウント → API アクセスキー に移動し、値をコピーします。

インストール

このディストリビューションは mcp-redmine-rest として公開されており、インストールされるコマンドは mcp-redmine-rest です。PyPI 上の短い名前 mcp-redmine は無関係のプロジェクトに属しています — このサーバーを期待してそれをインストールしないでください。

AI エージェントにこのリポジトリを指してセットアップを任せる場合は、llms-install.md がまさにそのために書かれています。

uv を使用する場合（推奨）

uv tool install mcp-redmine-rest

pip を使用する場合

pip install mcp-redmine-rest

ソースから

git clone https://github.com/alsimoes/mcp-redmine-rest.git
cd mcp-redmine-rest

python3 -m venv venv && source venv/bin/activate    # Linux/Mac

pip install -e .

Windows では、Git Bash/WSL シェルではなく py と PowerShell を使用してください — Windows で Unix スタイルのシェルから venv を作成または再作成すると、venv\pyvenv.cfg が Unix の home パスで上書きされ、以降 venv\Scripts\python.exe を起動するたびに No Python at '/usr/bin\python.exe'（または類似のエラー）で失敗します：

git clone https://github.com/alsimoes/mcp-redmine-rest.git
cd mcp-redmine-rest

py -3 -m venv venv
.\venv\Scripts\Activate.ps1

pip install -e .

設定

サーバーは環境変数から設定を読み取ります：

クライアント設定からキーを除外する

環境にない値は .env ファイルから読み取られるため、API キーを MCP クライアントの設定に平文で置く必要はありません。.env.example をリポジトリルートの .env にコピーして記入してください — 上記の表のすべての変数が尊重されるため、クライアントの env ブロックは完全に削除できます：

REDMINE_URL=https://redmine.example.com
REDMINE_API_KEY=your_api_key_here
REDMINE_TIMEOUT=15

このファイルは gitignore されています。環境にすでに存在する変数が常に優先されるため、クライアント設定の env ブロックは依然としてそれを上書きします。ファイルを別の場所に置くには、REDMINE_ENV_FILE にそのフルパスを設定します。

これは特に Claude Desktop で重要です：Claude Desktop は MCP サーバーを、自身が構築した最小限の環境で起動するため、シェルでエクスポートしたり setx で設定した変数はサーバーに届きません。env ブロックまたは .env ファイルを使用してください。

Claude Desktop

Claude Desktop の設定ファイルを編集（または作成）します：

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

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

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

{
  "mcpServers": {
    "redmine": {
      "command": "mcp-redmine-rest",
      "env": {
        "REDMINE_URL": "https://redmine.example.com",
        "REDMINE_API_KEY": "your_api_key_here"
      }
    }
  }
}

uv tool install / pip install ではなくソースからインストールした場合は、command を仮想環境のインタープリターに指定し、スクリプトを引数として渡します：

{
  "mcpServers": {
    "redmine": {
      "command": "/full/path/to/mcp-redmine/venv/bin/python",
      "args": ["-m", "mcp_redmine"],
      "env": {
        "REDMINE_URL": "https://redmine.example.com",
        "REDMINE_API_KEY": "your_api_key_here"
      }
    }
  }
}

Windows では、command を venv\Scripts\python.exe に指定します（JSON では \\ をエスケープ）：

{
  "mcpServers": {
    "redmine": {
      "command": "C:\\full\\path\\to\\mcp-redmine\\venv\\Scripts\\python.exe",
      "args": ["-m", "mcp_redmine"],
      "env": {
        "REDMINE_URL": "https://redmine.example.com",
        "REDMINE_API_KEY": "your_api_key_here"
      }
    }
  }
}

その後、Claude Desktop を再起動します。ツールアイコン（🔨）に Redmine ツールが利用可能として表示されるはずです。

Claude Code

claude mcp add redmine \
  --env REDMINE_URL=https://redmine.example.com \
  --env REDMINE_API_KEY=your_api_key_here \
  -- mcp-redmine-rest

以下で確認します：

claude mcp list

Cline（VS Code）

パレットから MCP 設定を開きます — Ctrl+Shift+P → Cline: Open MCP Config File — または Cline サイドバーの「MCP Servers」の横にある歯車をクリックし、Configure MCP Servers を選択します。どちらでも cline_mcp_settings.json が開くので、そこにサーバーを追加します：

{
  "mcpServers": {
    "redmine": {
      "command": "mcp-redmine-rest",
      "env": {
        "REDMINE_URL": "https://redmine.example.com",
        "REDMINE_API_KEY": "your_api_key_here"
      }
    }
  }
}

手動でファイルを編集するのではなく、パレットコマンドを使用してください — ファイルは VS Code のグローバルストレージの奥深く （.../User/globalStorage/saoudrizwan.claude-dev/settings/cline_mcp_settings.json）にあり、パスはプラットフォームごとに異なります。

mcp-redmine-rest が VS Code が見る PATH にない場合は、代わりにモジュール形式を使用します — "command" をパッケージがインストールされているインタープリターに指定し、"args": ["-m", "mcp_redmine"] を渡します。上記の Claude Desktop の例とまったく同じです。

ウィンドウをリロード（Ctrl+Shift+P → Developer: Reload Window）すると、サーバーが「MCP Servers」の下で接続済みとして表示されるはずです。ワークスペースの .mcp.json と Add-Server UI をカバーするより詳しいチュートリアルは CLINE_SETUP.md にあります。

その他の MCP クライアント

ローカルプロセスを起動して stdio で MCP を話せるクライアントはすべて同じように動作します：REDMINE_URL と REDMINE_API_KEY を環境に設定した状態で mcp-redmine-rest（または python -m mcp_redmine）を実行します。

ローカルでの実行（任意）

クライアントにサーバーを組み込む前に簡単な動作確認をするのに便利です：

cp .env.example .env   # then edit .env with your values
export $(grep -v '^#' .env | xargs)   # or use a tool like direnv
mcp-redmine-rest

接続エラーがなければサーバーは準備完了です — stdin/stdout で MCP メッセージを待機するため、ターミナルで何も起こらないように見えるのは正常です。停止するには Ctrl+C を押します。

使用例

設定が完了したら、エージェントに話しかけるだけです：

• 「Website プロジェクトで自分に割り当てられた未完了のチケットを一覧表示して。」

• 「Website に『ログインボタンがモバイルで応答しない』というバグを作成して、優先度は高で。」

• 「チケット #101、#104、#110 を進行中に移動して、Alice に割り当てて。」

• 「今日のチケット #204 に 3.5 時間、活動は開発で記録して。」

• 「Infra プロジェクトの Wiki ページ『Deployment』には何が書いてある？」

• 「全プロジェクトで『timeout』を検索して。」

利用可能なツール

リソース別にグループ化された 73 のツール。完全なリファレンス — シグネチャ、パラメータ、戻り値の形式、および重要な注意点（precedes がチケットを再スケジュールする方法や、list_custom_fields に管理者権限が必要なことなど）— は docs/TOOLS.md にあります。

API カバレッジ

この 2 つの省略は意図的なものです。 delete_project と delete_user は 取り消しができず、他の人のコンテンツ（issues、time entries、wiki pages、 authorship）も巻き添えにして削除してしまいます。archive_project と status=3 を指定した update_user は、実際のユースケースを可逆的にカバーします。 本当の削除は Web UI の操作として残されており、そこでは確認が明示的で人間が行います。 詳細な理由については SECURITY.md を参照してください。

Trackers、issue ステータス、優先度、ロールには Redmine API に書き込み操作が ありません。これらは Administration でのみ設定可能です。これはこのサーバーの 欠落ではありません。

安定版 REST API の範囲外、したがってこのサーバーのスコープ外となるもの： リポジトリとチェンジセット、wiki ページの保護、インスタンス全体の設定画面。

エラーメッセージ

エラーは中央で処理されます：Redmine が呼び出しを拒否すると、サーバーは レスポンスボディを読み取ります — そこに実際の説明が errors フィールドに あります — そしてその文を返します。有用なボディがない場合は、HTTP ステータスと 考えられる理由にフォールバックします：

これは読み取り・書き込みを問わず、すべてのツールに適用されます。

トラブルシューティング

• 「REDMINE_URL and REDMINE_API_KEY must be set」：サーバーは起動時に 設定をチェックし、壊れた状態で起動する代わりにこのメッセージを表示して 即座に終了します。MCP クライアントの設定の env ブロックを確認してください。

• すべての呼び出しがネットワークエラーで失敗する：サーバープロセスが 実際に REDMINE_URL に到達できることを確認してください — MCP クライアントは サーバーをローカルプロセスとして実行するため、ブラウザではなく、お使いの マシンと同じネットワークアクセスが必要です。

• すべての呼び出しで 401：API キーが間違っているか、Redmine の設定で 「REST ウェブサービスを有効にする」がオフになっています。

• 特定のツールで 403：通常、API キーを所有するユーザーのロールに 権限がありません。get_role はロールが持つ権限を正確に表示します。

• 期待どおりに動作するはずのツールが 404 を返す：いくつかのエンドポイント （update_journal_note、update_news/delete_news、 update_attachment）は特定の Redmine バージョンで追加されました — 各ツールの最小バージョンについては docs/TOOLS.md を参照してください。

セキュリティ

完全なモデルについては SECURITY.md を参照してください。要約すると： API キーはそれを所有するユーザーと同等のアクセス権を付与するため、エージェントに 実行させたい範囲にスコープされたロールを持つ専用の Redmine ユーザーを作成し、 そのユーザーのキーを使用してください — このサーバーのコードを編集して エージェントを制限しようとしないでください。

REDMINE_UPLOAD_ROOTS を設定するまで、ファイルアップロードは無効です。 ローカルファイルをアップロードする 3 つのツール（attach_file_to_issue、 attach_file_to_wiki_page、upload_project_file）は、デフォルトですべての パスを拒否します。これはまさに、エージェントが注入されたコンテンツ（issue の コメント、wiki ページ）によって、読むことを意図されていないファイルを アップロードするよう誘導される可能性があるためです。 SECURITY.md を参照してください。

コントリビューション

CONTRIBUTING.md を参照してください。

ライセンス

MIT