redmine-mcp-stdio

redmine-mcp-stdio

Redmine 用のローカルな Model Context Protocol サーバー（stdio）です。MCP クライアント（Cursor、VS Code、Claude、Codex、Windsurf、Cline、Zed、JetBrains AI など）から接続すれば、エディターから直接 Redmine のチケット、プロジェクト、作業時間を扱えます。

ツール

ツール	内容	主なパラメーター
list_issues	チケットの一覧表示・フィルタリング、ページネーション対応	project_id、status_id、assigned_to_id、query、limit、offset、all
get_issue	1 件のチケットの詳細、コメント／履歴、添付ファイル	id、include_journals（デフォルトは true）
list_projects	アクセス可能なプロジェクト	limit
get_project	プロジェクトの詳細、バージョン、メンバー	id
create_issue	チケットを作成	project_id、subject、description、tracker_id、priority_id、assigned_to_id、status_id
update_issue	チケットのフィールドを更新	id と subject、status_id、priority_id、assigned_to_id、done_ratio、notes のいずれか
add_comment	チケットに注記を追加	id、notes
log_time	チケット／プロジェクトの作業時間を記録	issue_id または project_id、hours、activity_id、comments、spent_on
list_time_entries	作業時間の一覧表示、フィルタリング	issue_id、project_id、user_id、from、to、limit、offset
list_enumerations	トラッカー／ステータス／優先度／作業分類の ID	なし
search	全文検索（チケット、Wiki、ニュースなど）	q、project_id、types、titles_only、open_issues、limit、offset
get_current_user	API キーに紐づくアカウント（ID、ログイン名、名前）	なし

すべてのツールには MCP のツールアノテーション（readOnlyHint、destructiveHint など）が付属しているため、クライアントは読み取り専用の呼び出しを自動承認できます。

インストール

手動でインストールする必要はありません。クライアントは必要に応じて npx でサーバーを起動します。初回実行時にダウンロードされ、その後はキャッシュされます。接続でクライアントの設定を追加するだけです。

ローカルクローンから実行したい場合は、開発をご覧ください。

Redmine API キーを取得する

マイアカウント > API アクセスキー > 表示。

• 該当する項目がない場合は、管理者が 管理 > 設定 > API で REST API を有効にする必要があります。
• キーは、チケットの閲覧（書き込みの場合は作成・編集も）権限を持つユーザーのものである必要があります。

⚠️ API キーをコミットしないでください。ローカルで使用する場合は .env.example を .env にコピーしてください。.env は gitignore されています。

接続

サーバーは環境変数から REDMINE_URL と REDMINE_API_KEY を読み込みます。クライアントの MCP 設定の env ブロックで指定してください。

Cursor

~/.cursor/mcp.json（グローバル）またはプロジェクトのルートにある .cursor/mcp.json を編集します。

{
  "mcpServers": {
    "redmine": {
      "command": "npx",
      "args": ["-y", "redmine-mcp-stdio"],
      "env": {
        "REDMINE_URL": "https://redmine.your-company.com",
        "REDMINE_API_KEY": "your_key"
      }
    }
  }
}

Cursor を再読み込みし、設定 > MCP でサーバーを有効にします。

VS Code（GitHub Copilot）

ワークスペースの .vscode/mcp.json（またはユーザーの mcp.json）を編集します。最上位のキーは mcpServers ではなく servers です。

{
  "servers": {
    "redmine": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "redmine-mcp-stdio"],
      "env": {
        "REDMINE_URL": "https://redmine.your-company.com",
        "REDMINE_API_KEY": "your_key"
      }
    }
  }
}

Claude Code

claude mcp add redmine \
  --env REDMINE_URL=https://redmine.your-company.com \
  --env REDMINE_API_KEY=your_key \
  -- npx -y redmine-mcp-stdio

または、~/.claude.json / プロジェクトの .mcp.json を直接編集します（下記の Claude Desktop と同じ形式です）。

Claude Desktop

claude_desktop_config.json を編集します（macOS の場合：~/Library/Application Support/Claude/claude_desktop_config.json）。

{
  "mcpServers": {
    "redmine": {
      "command": "npx",
      "args": ["-y", "redmine-mcp-stdio"],
      "env": {
        "REDMINE_URL": "https://redmine.your-company.com",
        "REDMINE_API_KEY": "your_key"
      }
    }
  }
}

その後、Claude Desktop を再起動します。

Codex CLI

~/.codex/config.toml にサーバーテーブルを追加します。

[mcp_servers.redmine]
command = "npx"
args = ["-y", "redmine-mcp-stdio"]
env = { REDMINE_URL = "https://redmine.your-company.com", REDMINE_API_KEY = "your_key" }

node を nvm 経由でインストールしている場合は、which npx で確認できるフルパスを command に指定します。

Windsurf

~/.codeium/windsurf/mcp_config.json を編集します。

{
  "mcpServers": {
    "redmine": {
      "command": "npx",
      "args": ["-y", "redmine-mcp-stdio"],
      "env": {
        "REDMINE_URL": "https://redmine.your-company.com",
        "REDMINE_API_KEY": "your_key"
      }
    }
  }
}

Cascade で MCP サーバー > 管理 > 生の設定を表示 を開き、貼り付けてから更新します。キーを直接記述したくない場合は、${env:VAR} による展開にも対応しています。

Cline

Cline ペインで MCP Servers アイコンをクリックし、Configure MCP Servers を選択して cline_mcp_settings.json を開きます。

{
  "mcpServers": {
    "redmine": {
      "command": "npx",
      "args": ["-y", "redmine-mcp-stdio"],
      "env": {
        "REDMINE_URL": "https://redmine.your-company.com",
        "REDMINE_API_KEY": "your_key"
      }
    }
  }
}

Zed

Zed では MCP サーバーをコンテキストサーバーと呼びます。コマンドパレットを開いて zed: open settings を実行し、settings.json に追加します（"source": "custom" に注意してください）。

{
  "context_servers": {
    "redmine": {
      "source": "custom",
      "command": "npx",
      "args": ["-y", "redmine-mcp-stdio"],
      "env": {
        "REDMINE_URL": "https://redmine.your-company.com",
        "REDMINE_API_KEY": "your_key"
      }
    }
  }
}

Zed は保存時にサーバーを再起動するため、エディターを再読み込みする必要はありません。

JetBrains AI Assistant（2025.2+）

設定 > ツール > AI Assistant > Model Context Protocol (MCP) > 追加：

• 種類：stdio
• コマンド：npx（node を nvm 経由でインストールしている場合は、which npx で確認できるフルパスを使用します）
• 引数：-y redmine-mcp-stdio
• 環境変数：
  • REDMINE_URL=https://redmine.your-company.com
  • REDMINE_API_KEY=your_key

"新規および変更された MCP サーバーを自動的に有効にする" を有効にしてから、適用をクリックします。ステータスアイコンをクリックすると、12 個のツールが表示されます。チャットで / を使って呼び出してください。

ローカルでの確認（任意）

REDMINE_URL=https://redmine.your-company.com REDMINE_API_KEY=your_key npx -y redmine-mcp-stdio

プロセスが起動し、stdio 上で何も表示せずに待機するはずです（終了するには Ctrl+C を押します）。

トラブルシューティング

• Failed to connect / サーバーが起動しない： command はクライアントの環境で解決できる必要があります。node を nvm 経由でインストールしている場合、単独の npx が見つからないことがあります。which npx で確認できるフルパスをコマンドに指定してください。
• Missing REDMINE_URL or REDMINE_API_KEY： env ブロックが渡されていません。シェルではなく、MCP 設定に指定されていることを確認してください。
• Redmine 401 / 403： API キーが無効か、キーの所有者にその操作を行う権限がありません。
• Redmine 404： チケットまたはプロジェクトの ID が存在しないか、REDMINE_URL のホストが間違っています。

設定

変数	必須	デフォルト	説明
REDMINE_URL	はい	なし	Redmine インスタンスのベース URL（http/https）
REDMINE_API_KEY	はい	なし	個人用 API アクセスキー
REDMINE_TIMEOUT_MS	いいえ	10000	リクエストごとのタイムアウト（ミリ秒）
REDMINE_MAX_RETRIES	いいえ	2	指数バックオフによる 429/5xx の再試行回数

アーキテクチャ

コードはレイヤー構造になっており、各ツールグループに単一の HTTP クライアントを注入するため、ツールがトランスポートや process.env に直接触れることはありません：

src/
  index.ts            entry point: load config, build client, register tools, serve stdio
  config.ts           env parsing + validation (Zod) into a typed RedmineConfig
  version.ts          single source of the version string
  redmine/
    client.ts         RedmineClient: auth, timeout, retry, host pinning, secret redaction
    errors.ts         RedmineError / ConfigError + HTTP error normalization
    paths.ts          safe path-segment encoding + project-id validation
    types.ts          Redmine API response types
  tools/
    register.ts       wires every tool group onto the server
    issues.ts         list/get/create/update issues + add_comment
    projects.ts       list/get projects (versions, members)
    time-entries.ts   log_time, list_time_entries
    enumerations.ts   trackers / statuses / priorities / activities
    search.ts         full-text search across issues, wiki, news, ...
    users.ts          get_current_user
    helpers.ts        guard(), ok()/fail(), ToolResult
  format.ts           pure presentation helpers

開発

npm run build       # compile src/ to build/
npm run typecheck   # tsc --noEmit (strict)
npm run lint        # eslint
npm run format      # prettier --write
npm test            # build, then run the vitest suite
npm run check       # typecheck + lint + format:check + test (what CI runs)

リリースについては、CHANGELOG.md を参照してください。

セキュリティ

API キーがログに記録されることはなく、エラー出力では秘匿されます。リクエストは設定されたホストに固定され、パスパラメーターはエンコードされます。また、すべての呼び出しにはタイムアウトとレスポンスサイズの上限が設けられています。詳細と報告については、SECURITY.md を参照してください。

ライセンス

MIT です。LICENSE を参照してください。