mcp-redmine

Model Context Protocol 서버로, Claude(Desktop 또는 Code) — 또는 다른 MCP 클라이언트 — 를 REST API를 통해 Redmine 인스턴스에 연결합니다.

실질적으로 안정적인 Redmine REST API 전체를 포괄하는 73개의 도구를 제공합니다: 이슈, 관계, 프로젝트, 멤버십, 버전, 카테고리, 사용자, 그룹, 역할, 위키, 시간 추적, 첨부 파일, 프로젝트 파일, 뉴스, 검색. 에이전트를 Redmine 프로젝트에 연결하면 자연어 대화만으로 이슈를 읽고 관리하고, 시간을 기록하고, 위키 페이지를 편집하고, 사용자를 관리할 수 있습니다.

기능

• 이슈에 대한 전체 읽기/쓰기 지원: 일괄 업데이트, 관계, watcher, 댓글 포함.

• 프로젝트 관리: 프로젝트 생성/업데이트/보관, 멤버, 버전, 카테고리 관리.

• 사용자 및 그룹 관리: 의도적으로 "사용자 삭제" 또는 "프로젝트 삭제" 도구는 없음 — 보안 참조.

• 위키: 중첩 페이지 및 파일 첨부 포함.

• 시간 추적, 첨부 파일, 프로젝트 파일, 뉴스, 전체 텍스트 검색.

• 읽기 쉬운 오류: 모든 실패는 원시 스택 트레이스가 아닌 Redmine 자체 검증 응답에서 가져온 명확한 문장으로 반환됩니다.

• 실행할 것이 없음: MCP 클라이언트와 stdio로 통신하는 단일 Python 프로세스 — 데이터베이스, 호스팅할 서버, Docker 불필요.

Related MCP server: redmine-mcp

사전 요구 사항

• Python 3.10+

• REST API가 활성화된 Redmine 인스턴스:

  1. Redmine에서 관리 → 설정 → API로 이동하여 "REST 웹 서비스 활성화"를 켭니다(아직 켜져 있지 않은 경우).

  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을 In Progress로 이동하고 Alice에게 할당해 줘."

• "오늘 이슈 #204에 3.5시간을 기록해 줘, 활동은 Development."

• "Infra 프로젝트의 'Deployment' 위키 페이지에 뭐가 있지?"

• "모든 프로젝트에서 'timeout'을 검색해 줘."

사용 가능한 도구

리소스별로 그룹화된 73개 도구. 전체 참조 — 시그니처, 매개변수, 반환 형태, 그리고 중요한 주의 사항(precedes가 이슈를 재일정하는 방법이나 list_custom_fields에 관리자 권한이 필요한 이유 등) — 은 docs/TOOLS.md에 있습니다.

API 범위

두 가지 누락은 의도적입니다. delete_project와 delete_user는 되돌릴 수 없으며 다른 사람의 콘텐츠(이슈, 시간 항목, 위키 페이지, 작성자 정보)까지 함께 삭제합니다. archive_project와 status=3을 사용한 update_user는 실제 사용 사례를 되돌릴 수 있는 방식으로 처리합니다. 실제 삭제는 확인이 명시적이고 사람이 수행하는 웹 UI 작업으로 남아 있습니다. 전체 근거는 SECURITY.md를 참조하세요.

트래커, 이슈 상태, 우선순위, 역할은 Redmine API에 쓰기 작업이 없습니다. 관리(Administration)에서만 구성할 수 있습니다. 이는 이 서버의 결함이 아닙니다.

안정적인 REST API 외부에 있으므로 이 서버의 범위 밖입니다: 저장소 및 변경 집합, 위키 페이지 보호, 인스턴스 전체 설정 화면.

오류 메시지

오류는 중앙에서 처리됩니다. Redmine이 호출을 거부하면 서버는 응답 본문을 읽습니다. 실제 설명이 있는 곳은 errors 필드이며, 해당 문장을 반환합니다. 유용한 본문이 없으면 HTTP 상태와 예상되는 이유로 대체합니다:

이는 읽기와 쓰기 모두 모든 도구에 적용됩니다.

문제 해결

• "REDMINE_URL and REDMINE_API_KEY must be set": 서버는 시작 시 구성을 확인하고, 손상된 상태로 시작하는 대신 이 메시지와 함께 즉시 종료됩니다. MCP 클라이언트 구성의 env 블록을 확인하세요.

• 모든 호출이 네트워크 오류로 실패: 서버 프로세스가 실제로 REDMINE_URL에 도달할 수 있는지 확인하세요. MCP 클라이언트는 서버를 로컬 프로세스로 실행하므로 브라우저가 아닌 사용자 머신과 동일한 네트워크 액세스가 필요합니다.

• 모든 호출에서 401: API 키가 잘못되었거나 Redmine 설정에서 "REST 웹 서비스 활성화(Enable REST web service)"가 꺼져 있습니다.

• 특정 도구에서 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를 설정할 때까지 파일 업로드는 비활성화됩니다. 로컬 파일을 업로드하는 세 가지 도구(attach_file_to_issue, attach_file_to_wiki_page, upload_project_file)는 기본적으로 모든 경로를 거부합니다. 그 이유는 에이전트가 주입된 콘텐츠(이슈 댓글, 위키 페이지)에 의해 읽을 의도가 없었던 파일을 업로드하도록 유도될 수 있기 때문입니다. SECURITY.md를 참조하세요.

기여

CONTRIBUTING.md를 참조하세요.

라이선스

MIT