Redmine Fastmcp Server With Oauth

mcp-redmine-oauth — OAuth 対応 Redmine FastMCP サーバー

OAuth 2.0 認証を使用する、Redmine 向けの一元デプロイ型 MCP サーバーです。管理者が一度デプロイすれば、ユーザーは Redmine で認証するだけで接続できます。API キーやユーザーごとのセットアップは不要です。FastMCP 3 で構築されています。

仕組み

MCP Client (Claude Desktop, MCP Inspector, …)
        │  MCP over Streamable HTTP
        │  Authorization: Bearer <fastmcp-jwt>
        ▼
┌─────────────────────────────┐
│      FastMCP 3 Server       │
│  OAuthProxy (port 8000)     │──── token exchange ────▶ Redmine OAuth
│  Token store (in-memory)    │◀─── access token ────────
│                             │
│  Tools                      │──── REST API ───────────▶ Redmine API
└─────────────────────────────┘

MCP クライアントに渡されるのは、FastMCP が発行する JWT だけです。Redmine の OAuth トークンはサーバー側に保存され、クライアントに公開されることはありません。

前提条件

• Python 3.11+
• REST API が有効になっている Redmine 6.1+ の稼働インスタンス
• Redmine に登録済みの OAuth アプリケーション（下記を参照）

Redmine のセットアップ

1. REST API を有効にする

管理 → 設定 → API → REST Web サービスを有効にする（チェックして保存します）。

2. OAuth アプリケーションを登録する

管理 → アプリケーション → 新しいアプリケーション

フィールド	値
リダイレクト URI	http://<MCP_BASE_URL>/auth/callback
機密クライアント	はい
スコープ	すべての機能を利用するには、必須スコープをすべて有効にします

生成された Client ID と Client Secret をコピーします。

セットアップ

git clone https://github.com/tuzumkuru/mcp-redmine-oauth.git
cd mcp-redmine-oauth
cp .env.example .env

値を入力します。

REDMINE_URL=http://your-redmine-host
REDMINE_CLIENT_ID=your-client-id
REDMINE_CLIENT_SECRET=your-client-secret

実行

pip install -e .
mcp-redmine-oauth

MCP サーバーは http://localhost:8000/mcp で利用できます。

MCP Inspector でテストするには、次のようにします。

npx @modelcontextprotocol/inspector

http://localhost:6274 を開き、トランスポートを Streamable HTTP に設定して、http://localhost:8000/mcp を入力します。

Docker での実行

docker compose up --build

コンテナは .env から設定を読み込みます。MCP_BASE_URL はサーバーに外部からアクセスできる URL に設定してください（他のマシンからクライアントが接続する場合は、localhost にしないでください）。

ホスト側のポートを変更するには、.env の MCP_HOST_PORT を設定します（デフォルトは 8000 です）。

環境変数

変数	必須	デフォルト	説明
REDMINE_URL	はい	—	Redmine インスタンスのベース URL
REDMINE_CLIENT_ID	はい	—	OAuth アプリの Client ID
REDMINE_CLIENT_SECRET	はい	—	OAuth アプリの Client Secret
REDMINE_SCOPES	いいえ	(宣言されたすべてのスコープ)	許可リストフィルター：Redmine アプリがサポートするスコープをスペース区切りで指定します（スコープの処理を参照）
MCP_HOST	いいえ	0.0.0.0	バインドするホスト
MCP_PORT	いいえ	8000	バインドするポート
MCP_BASE_URL	いいえ	http://localhost:MCP_PORT	OAuth リダイレクトに使用する外部公開 URL
REDMINE_PUBLIC_URL	いいえ	REDMINE_URL	ユーザーがブラウザーで開く Redmine の URL。下書きリンクに使用します。サーバーが内部アドレスで Redmine にアクセスする場合に設定します

利用可能なツールとリソース

コンポーネント	種類	必要なスコープ	説明
get_issue_details	ツール	view_issues	説明、カスタムフィールド、履歴を含むRedmineのチケットをIDで取得します
search_issues	ツール	view_issues, search_project	ページネーションに対応したチケットの全文検索です
list_issues	ツール	view_issues	フィルター（プロジェクト、担当者、ステータス、トラッカー、並べ替え）を指定してチケットを一覧表示します
get_issue_relations	ツール	view_issues	チケットの関連（ブロック、ブロックされている、関連など）を取得します
get_project_details	ツール	view_project	トラッカー、カテゴリ、有効なモジュールを含むプロジェクトの詳細です
get_project_versions	ツール	view_project	ステータスと期日を含むプロジェクトのバージョン／マイルストーンです
list_time_entries	ツール	view_time_entries	フィルター（プロジェクト、ユーザー、日付範囲）を指定して作業時間を一覧表示します
create_issue	ツール	add_issues	件名、トラッカー、優先度、担当者などを指定して新しいチケットを作成します
update_issue	ツール	edit_issues	既存のチケットを更新します（ステータス、担当者、メモなど）
create_project	ツール	add_project	新しいRedmineプロジェクトを作成します
update_project	ツール	edit_project	プロジェクト名、説明、公開設定、トラッカーを更新します
get_wiki_page	ツール	view_wiki_pages	プロジェクトのWikiページを取得します
update_wiki_page	ツール	edit_wiki_pages	Wikiページを作成または更新します
rename_wiki_page	ツール	rename_wiki_pages	オプションでリダイレクトを設定してWikiページの名前を変更します
draft_new_issue	ツール	(ログインのみ)	提案された値を入力済みのRedmineの新規チケットフォームへのリンクです。ユーザーが送信するまで保存されません
draft_issue_update	ツール	(ログインのみ)	提案された変更とコメントを入力済みのチケット編集フォームへのリンクと、チケットページへのリンクです
draft_new_project	ツール	(ログインのみ)	入力済みのRedmineの新規プロジェクトフォームへのリンクです。プロジェクトの追加が許可されているユーザー、または親プロジェクトのサブプロジェクトの場合のみ利用できます
summarize_ticket	プロンプト	view_issues	次のステップを含む、チケットの簡潔な要約を生成します
draft_bug_report	プロンプト	view_project	簡単なメモから、構成化されたバグレポートの草案を作成します
redmine://projects/active	リソース	view_project	アクティブなプロジェクトを一覧表示します
redmine://trackers	リソース	view_project	利用可能なトラッカーを一覧表示します
redmine://issue-statuses	リソース	view_issues	IDとクローズ済みフラグを含むすべてのチケットステータスです
redmine://enumerations/priorities	リソース	view_issues	IDを含むチケットの優先度レベルです
redmine://users/me	リソース	(認証のみ)	現在認証されているユーザーのプロフィールです

予定：トークンの永続ストレージ、スコープに応じたツールの動的な無効化、構造化ログ。

必要なRedmineスコープ

Redmine OAuthアプリケーションでこれらのスコープを有効にしてください（管理 → アプリケーション）。アプリケーション設定に表示されるRedmineのカテゴリごとに分類されています。

プロジェクト

Redmineの権限	スコープ識別子	使用箇所
プロジェクトの表示	view_project	get_project_details、get_project_versions、redmine://projects/active、redmine://trackers、draft_bug_report
プロジェクトの検索	search_project	search_issues
プロジェクトの作成	add_project	create_project
プロジェクトの編集	edit_project	update_project

チケット管理

Redmineの権限	スコープ識別子	使用箇所
チケットの表示	view_issues	get_issue_details、search_issues、list_issues、get_issue_relations、redmine://issue-statuses、redmine://enumerations/priorities、summarize_ticket
チケットの追加	add_issues	create_issue
チケットの編集	edit_issues	update_issue

作業時間の記録

Redmineの権限	スコープ識別子	使用箇所
作業時間の表示	view_time_entries	list_time_entries

Wiki

Redmine の権限	スコープ識別子	使用するツール
Wiki の表示	view_wiki_pages	get_wiki_page
Wiki ページの編集	edit_wiki_pages	update_wiki_page
Wiki ページの名前変更	rename_wiki_pages	rename_wiki_page

スコープが有効になっていない場合、それを必要とするツールは呼び出し時に説明的なエラーを返します。

スコープの処理

各ツールとリソースは、@requires_scopes デコレーターを使用して必要な OAuth スコープを宣言します。サーバーは宣言されたすべてのスコープを自動的に収集し、OAuth 認証時に要求します。

Redmine の OAuth アプリが上記のスコープの一部のみで設定されている場合、エラー "The requested scope is invalid, unknown, or malformed" を回避するため、REDMINE_SCOPES を設定してください。

REDMINE_SCOPES=view_issues view_project

設定すると、ツールで宣言されたスコープと REDMINE_SCOPES の共通部分のみが要求されます。必要なスコープがすべて含まれていないツール（例：search_issues には search_project が必要）は、OAuth フロー全体を中断する代わりに、呼び出し時に説明的なエラーを返します。

省略した場合は、ツールで宣言されたすべてのスコープが要求されます。Redmine アプリですべてのスコープが有効になっている場合は、この設定で動作します。

アーキテクチャ

OAuth フロー、トークンの保存、モジュール設計の詳細については、docs/architecture.md を参照してください。