redmine-mcp

Redmine을 위한 상태 비저장(stateless) Model Context Protocol 서버입니다. 모든 Redmine 인스턴스 앞에 배치하여 Claude(또는 MCP를 지원하는 LLM 클라이언트)가 각 사용자의 API 키를 사용하여 사용자를 대신해 이슈를 읽고 쓰고, 시간을 기록하고, 위키를 탐색하고, 프로젝트를 검색할 수 있도록 합니다.

• 상태 없음(Zero state): 데이터베이스, 세션, 공유 비밀 키가 없습니다. 서버는 요청과 함께 전달된 API 키를 사용하여 각 요청을 Redmine으로 전달합니다.

• 하나의 서버, 다수의 사용자: 운영자가 구성하는 유일한 설정은 업스트림 REDMINE_URL입니다. 각 MCP 클라이언트는 자체 X-Redmine-API-Key를 제공합니다. 권한은 Redmine의 설정을 따릅니다.

• 커버리지: 이슈(CRUD + 노트), 프로젝트, 멤버십, 사용자, 시간 기록, 위키(PUT-upsert), 첨부 파일(업로드 + 다운로드), 전체 텍스트 검색, 상태, 추적기, 카테고리, 사용자 정의 필드, 열거형.

빠른 시작

로컬 (uv)

uv sync
REDMINE_URL=https://redmine.example.com uv run redmine-mcp

MCP 엔드포인트는 이제 http://127.0.0.1:8080/mcp에 있습니다.

컨테이너 (GHCR)

docker run --rm -p 8080:8080 \
  -e REDMINE_URL=https://redmine.example.com \
  ghcr.io/kalvadtech/redmine-mcp:latest

이 이미지는 다단계 Alpine 기반이며, 루트가 아닌 사용자로 실행되고 8080 포트를 노출합니다.

Related MCP server: Redmine MCP Server

MCP 클라이언트에 연결하기

내 계정 > API 액세스 키에서 Redmine API 키를 찾으세요. 아래의 두 클라이언트 모두 Streamable HTTP를 통해 동일한 MCP 엔드포인트와 통신하며, 다른 클라이언트 구성은 필요하지 않습니다.

Claude Code

프로젝트 루트의 .mcp.json:

{
  "mcpServers": {
    "redmine": {
      "type": "http",
      "url": "http://127.0.0.1:8080/mcp",
      "headers": {
        "X-Redmine-API-Key": "your-40-char-key"
      }
    }
  }
}

opencode

프로젝트 루트(또는 opencode 구성 디렉토리)의 opencode.json:

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "redmine": {
      "type": "remote",
      "url": "http://127.0.0.1:8080/mcp",
      "enabled": true,
      "headers": {
        "X-Redmine-API-Key": "{env:REDMINE_API_KEY}"
      }
    }
  }
}

opencode는 headers에서 {env:VAR} 보간을 지원하므로 API 키를 구성 파일에 노출하지 않아도 됩니다: REDMINE_API_KEY=... opencode.

구성

redmine-mcp의 CLI 플래그:

--host        bind address (default 127.0.0.1)
--port        port (default 8080)
--log-level   uvicorn log level (default info)

REDMINE_URL이 누락되었거나 http(s)가 아닌 경우 서버는 부팅 시 즉시 실패합니다.

인증 모델

Redmine URL은 사용자가 제공하는 것이 아니라 REDMINE_URL을 통해 배포 시 고정됩니다. 이는 SSRF 위험을 제거합니다: 클라이언트는 서버가 임의의 호스트를 가리키도록 할 수 없습니다.

클라이언트가 보내는 유일한 자격 증명은 X-Redmine-API-Key 헤더에 포함된 자체 Redmine API 키입니다. 서버는 이를 Redmine으로 동일한 헤더로 전달하고(따라서 쿼리 문자열로 Redmine 액세스 로그에 남지 않음), 한 번의 요청을 수행하는 데 사용한 후 폐기합니다. 캐싱, 공유 서비스 계정, 가장(impersonation)은 없습니다.

도구

59개의 도구가 Redmine의 REST API를 통해 노출되는 모든 리소스 제품군을 다룹니다. 도구 목록은 페이징을 쉽게 하기 위해 {items, total_count, limit, offset}을 반환합니다.

이슈

• list_issues (프로젝트, 상태, 담당자, 추적기, 카테고리, 버전, 저장된 쿼리, 자유 텍스트 쿼리, 정렬, 포함)

• get_issue (포함: 저널, 첨부 파일, 관계, 하위 이슈, 관찰자)

• create_issue (포함: uploads 토큰, custom_fields, watcher_user_ids)

• update_issue (포함: notes, private_notes)

• add_issue_note (간단한 래퍼)

• delete_issue

이슈 관계

• list_issue_relations, get_relation, create_issue_relation (관련/차단/선행 등, 선행/후행의 경우 delay 포함), delete_relation

저널 (이슈 노트)

• update_journal_note - 기존 노트의 텍스트나 공개 범위를 편집합니다. 새 노트를 추가하려면 add_issue_note를 사용하세요.

프로젝트 및 버전

• list_projects, get_project

• list_versions, get_version, create_version, update_version, delete_version

멤버십

• list_memberships, get_membership, add_project_member (사용자 또는 그룹), update_membership, remove_membership

사용자, 내 계정, 그룹, 역할

• list_users, get_user (문자열 "current" 허용)

• get_my_account, update_my_account

• list_groups, get_group, create_group, update_group, delete_group, add_user_to_group, remove_user_from_group

• list_roles, get_role (권한 포함)

시간 기록

• list_time_entries (날짜 범위, 사용자, 프로젝트, 이슈)

• create_time_entry (이슈 또는 프로젝트, 시간, 활동, spent_on, 코멘트)

• update_time_entry, delete_time_entry

위키

• list_wiki_pages, get_wiki_page (버전 포함)

• create_or_update_wiki_page (PUT-upsert)

• delete_wiki_page

첨부 파일 및 파일

• get_attachment, download_attachment (25 MiB 제한, base64 출력)

• upload_attachment (create_issue / update_issue에서 uploads를 통해 첨부할 토큰 반환)

• list_files, upload_file (일회성 업로드 + 프로젝트의 파일 영역에 첨부, 선택적 version_id 및 설명 포함)

뉴스, 쿼리, 검색 및 메타데이터

• list_news (프로젝트 간 또는 프로젝트별)

• list_queries (저장된 쿼리; list_issues에 query_id로 ID 전달)

• search (이슈, 뉴스, 문서, 위키 등 전체 텍스트 검색)

• list_issue_statuses, list_trackers, list_issue_categories, list_custom_fields

• list_issue_priorities, list_time_entry_activities, list_document_categories

배포

단일 Redmine 인스턴스의 경우 환경당 하나의 컨테이너를 실행하세요:

docker run -d --name redmine-mcp \
  --restart unless-stopped \
  -p 8080:8080 \
  -e REDMINE_URL=https://redmine.example.com \
  ghcr.io/kalvadtech/redmine-mcp:latest

일반적인 리버스 프록시 및 TLS 종료 뒤에 배치하세요. MCP 프로토콜은 서버 측에서 HTTP 전용입니다. 사용자는 프록시를 통해 TLS를 얻습니다.

여러 Redmine 인스턴스의 경우, 자체 REDMINE_URL을 가진 인스턴스당 하나의 컨테이너를 실행하고 프록시에서 호스트 이름/경로별로 라우팅하세요.

개발

uv sync
uv run pytest
uv run ruff check .
uv run mypy src

테스트 제품군은 완전히 오프라인이며 respx를 사용하여 Redmine HTTP API를 모의(mock)합니다. 실제 Redmine에 대한 통합 테스트는 없습니다. 직접 준비하세요.

기여

풀 리퀘스트를 환영합니다. 다음을 준수해 주세요:

• Conventional Commits를 따를 것,

• 변경 사항을 간결하고 범위가 명확하게 유지할 것(커밋당 하나의 논리적 변경),

• 동작 변경에 대한 테스트를 추가하거나 업데이트할 것,

• PR을 열기 전에 pytest, ruff, mypy를 깨끗하게 통과할 것.

라이선스

MIT (c) 2026 Kalvad.