mc (MinIO Client)

mc는 local filesystem과 MinIO·Amazon S3 호환 object storage를 ls, cp, mirror, find 같은 명령으로 다루는 MinIO Client이다.

• Alias 형식: ALIAS/BUCKET/PREFIX/OBJECT
• 기본 설정 파일: Linux/macOS는 ~/.mc/config.json, Windows는 user profile 아래 .mc\config.json
• 일부 Linux package는 Midnight Commander의 mc와 이름 충돌을 피하려고 실행 파일을 mcli로 설치한다.
• MinIO Client와 MinIO Server는 별도로 release된다. 기능 호환성을 위해 release date가 가까운 client를 우선 사용한다.

MinIO가 제공하는 DEB package를 설치한다. 이 package의 실행 파일 이름은 mcli이다.

curl -O https://dl.min.io/client/mc/release/linux-amd64/mc.deb
sudo apt install ./mc.deb
mcli --version

ARM64에서는 URL의 linux-amd64를 linux-arm64로 바꾼다. mc 이름이 필요하면 아래 standalone binary 방식을 사용한다.

MinIO가 제공하는 RPM package를 설치한다. package 설치 환경에서는 mcli 명령을 사용한다.

sudo dnf install https://dl.min.io/client/mc/release/linux-amd64/mc.rpm
mcli --version

ARM64에서는 URL의 linux-amd64를 linux-arm64로 바꾼다.

curl -O https://dl.min.io/client/mc/release/linux-amd64/mc
curl -O https://dl.min.io/client/mc/release/linux-amd64/mc.sha256sum
sha256sum -c mc.sha256sum
chmod +x mc
sudo install -m 0755 mc /usr/local/bin/mc
mc --version

brew install minio/stable/mc
mc --version

MinIO upstream은 공식 Windows binary를 제공한다. 공식 winget 설치 방법은 제공하지 않으므로 binary를 내려받고 신뢰할 수 있는 PATH directory에 둔다.

Invoke-WebRequest -Uri "https://dl.min.io/client/mc/release/windows-amd64/mc.exe" -OutFile ".\mc.exe"
.\mc.exe --version

docker pull minio/mc
docker run --rm minio/mc ls play

다른 endpoint를 등록하려면 interactive shell에서 mc alias set을 실행한다.

docker run --rm -it --entrypoint=/bin/sh minio/mc

mc [GLOBAL_FLAGS] COMMAND [COMMAND_FLAGS] [ARGUMENTS]

• mc [GLOBAL_FLAGS] COMMAND [COMMAND_FLAGS] [ARGUMENTS]
• package가 mcli를 설치한 환경에서는 아래 모든 mc를 mcli로 바꾼다.

• –config-dir DIRECTORY, -C DIRECTORY: configuration directory 지정. MC_CONFIG_DIR로도 설정할 수 있다.
• –json: JSON Lines 형식으로 출력한다.
• –quiet, -q: 일반 출력을 줄인다.
• –no-color: ANSI color를 끈다.
• –disable-pager, –dp: pager 없이 raw stdout으로 출력한다.
• –debug: debug output을 표시한다.
• –resolve HOST[:PORT]=IP: command별 hostname 해석을 지정한다.
• –insecure: TLS certificate 검증을 끈다. production에서는 사용하지 않는다.
• –limit-upload RATE, –limit-download RATE: transfer rate를 제한한다.
• –custom-header KEY:VALUE, -H KEY:VALUE: HTTP header를 추가한다.
• –help, -h: 도움말을 표시한다.
• –version: client version을 표시한다.

• mc alias list [ALIAS]: 등록된 endpoint alias를 확인한다.
• mc alias set ALIAS URL ACCESS_KEY SECRET_KEY: S3-compatible endpoint와 credential을 등록하거나 갱신한다.
• mc alias remove ALIAS: 저장한 alias를 제거한다.
• mc ping ALIAS: endpoint connectivity를 연속 확인한다.
• mc ready ALIAS: cluster의 read/write readiness를 확인한다.

mc alias set local https://minio.example.com "$MINIO_ACCESS_KEY" "$MINIO_SECRET_KEY"
mc alias list local
mc admin info local

• mc mb ALIAS/BUCKET: bucket을 만든다.
• mc ls ALIAS: bucket 목록을 표시한다.
• mc ls ALIAS/BUCKET[/PREFIX]: object 목록을 표시한다.
• mc du ALIAS/BUCKET[/PREFIX]: 사용량을 집계한다.
• mc rb ALIAS/BUCKET: 빈 bucket을 삭제한다.
• mc version enable ALIAS/BUCKET: bucket versioning을 활성화한다.
• mc version suspend ALIAS/BUCKET: 새 version 생성을 중지한다.
• mc version info ALIAS/BUCKET: versioning 상태를 확인한다.

mc mb local/backups
mc ls local
mc version enable local/backups

• mc cp SOURCE TARGET: local/remote object를 복사한다. directory는 –recursive를 사용한다.
• mc put LOCAL_FILE ALIAS/BUCKET[/OBJECT]: local file을 upload한다.
• mc get ALIAS/BUCKET/OBJECT LOCAL_PATH: object를 local에 저장한다.
• mc mv SOURCE TARGET: object를 이동한다.
• mc cat ALIAS/BUCKET/OBJECT: object 내용을 stdout으로 출력한다.
• mc stat ALIAS/BUCKET/OBJECT: object metadata를 확인한다.
• mc find ALIAS/BUCKET[/PREFIX] [OPTIONS]: 조건에 맞는 object를 찾는다.
• mc rm ALIAS/BUCKET/OBJECT: object를 삭제한다.

mc cp report.pdf local/archive/
mc cp --recursive ./photos/ local/media/photos/
mc cp local/archive/report.pdf .
mc --json ls local/archive/
mc stat local/archive/report.pdf

• mc mirror SOURCE TARGET: source를 target에 mirror한다.
• mc diff FIRST SECOND: 두 path의 object name, size, date 차이를 표시한다.
• mc watch ALIAS/BUCKET[/PREFIX]: object event를 관찰한다.

mc diff ./backup local/backups
mc mirror --overwrite ./backup local/backups

• mc share upload –expire DURATION ALIAS/BUCKET/OBJECT: upload용 temporary URL을 만든다.
• mc share download –expire DURATION ALIAS/BUCKET/OBJECT: download용 temporary URL을 만든다.
• mc share list ALIAS/BUCKET[/PREFIX]: 생성한 share URL을 나열한다.

mc share upload --expire 1h local/incoming/report.pdf
mc share download --expire 1h local/archive/report.pdf

• mc anonymous get ALIAS/BUCKET[/PREFIX]: 현재 anonymous policy를 확인한다.
• mc anonymous set POLICY ALIAS/BUCKET[/PREFIX]: none, private, public, download, upload policy를 지정한다.

mc anonymous get local/public-assets
mc anonymous set download local/public-assets

admin command는 MinIO Server 관리 API를 사용하므로 S3-compatible service 전반에 적용되지 않는다.

• mc admin info ALIAS: server/cluster 정보를 확인한다.
• mc admin trace ALIAS: API operation trace를 실시간 표시한다.
• mc admin logs ALIAS [NODE]: server log를 확인한다.
• mc admin user add ALIAS USER SECRET_KEY: built-in user를 만들거나 password를 갱신한다.
• mc admin user info ALIAS USER: user 정보를 확인한다.
• mc admin policy attach ALIAS POLICY –user USER: user에게 policy를 연결한다.

mc admin info local
mc admin user add local app-reader "$MINIO_NEW_USER_SECRET"
mc admin policy attach local readonly --user app-reader
mc admin user info local app-reader

현재 작업 환경에는 mc가 설치되어 있지 않아 최신 mc –help live output은 수록하지 않았다. 설치된 환경에서 아래 명령으로 확인한다.

mc --help
mc COMMAND --help

mc version --help (기존 기록)

NAME:
  mc version - manage bucket versioning
 
USAGE:
  mc version COMMAND [COMMAND FLAGS | -h] [ARGUMENTS...]
 
COMMANDS:
  enable   enable bucket versioning
  suspend  suspend bucket versioning
  info     show bucket versioning status
 
FLAGS:
  --config-dir value, -C value     path to configuration folder (default: "/home/master/.mc") [$MC_CONFIG_DIR]
  --quiet, -q                      disable progress bar display [$MC_QUIET]
  --disable-pager, --dp            disable mc internal pager and print to raw stdout [$MC_DISABLE_PAGER]
  --no-color                       disable color theme [$MC_NO_COLOR]
  --json                           enable JSON lines formatted output [$MC_JSON]
  --debug                          enable debug output [$MC_DEBUG]
  --resolve value                  resolves HOST[:PORT] to an IP address. Example: minio.local:9000=10.10.75.1 [$MC_RESOLVE]
  --insecure                       disable SSL certificate verification [$MC_INSECURE]
  --limit-upload value             limits uploads to a maximum rate in KiB/s, MiB/s, GiB/s. (default: unlimited) [$MC_LIMIT_UPLOAD]
  --limit-download value           limits downloads to a maximum rate in KiB/s, MiB/s, GiB/s. (default: unlimited) [$MC_LIMIT_DOWNLOAD]
  --custom-header value, -H value  add custom HTTP header to the request. 'key:value' format.
  --help, -h                       show help

Linux package가 MinIO Client를 mcli로 설치할 수 있다. 다음 명령으로 어느 executable이 실행되는지 확인한다.

command -v mc
command -v mcli
mcli --version

정상 CA chain을 구성하거나 조직 CA certificate를 ~/.mc/certs/CAs/에 추가한다. –insecure는 certificate 검증을 비활성화하므로 임시 진단 외에는 사용하지 않는다.

• mc alias list ALIAS로 endpoint가 맞는지 확인한다.
• credential에 대상 bucket/prefix action 권한이 있는지 확인한다.
• mc admin policy attach는 MinIO가 관리하는 user/group용이다. external IdP user는 해당 IdP 정책 흐름을 사용한다.

일부 S3-compatible endpoint는 path-style lookup이 필요하다.

mc alias set local https://s3.example.com "$MINIO_ACCESS_KEY" "$MINIO_SECRET_KEY" --path on

• mc는 filesystem, MinIO, Amazon S3와 S3-compatible service를 대상으로 한다. 제3자 service는 구현 차이로 일부 command/option이 동작하지 않을 수 있다.
• mc admin은 MinIO-specific 관리 command이다.
• current client와 오래된 server 또는 그 반대 조합에서는 새 command가 지원되지 않을 수 있다.
• DEB/RPM package의 mcli와 standalone/Homebrew의 mc는 같은 client 계열이므로 문서의 executable 이름만 바꾸어 사용한다.

기존 페이지에 기록된 다음 형식은 현재 공식 top-level command 목록과 일치하지 않거나 오타가 있어 보존만 한다.

• mc presign put PATH: upload URL은 mc share upload PATH를 사용한다.
• mc presign get PATH: download URL은 mc share download PATH를 사용한다.
• mc anonymouse set AUTHORITY BUCKET: 오타를 수정한 mc anonymous set POLICY ALIAS/BUCKET을 사용한다.
• 과거 기록의 admin info BUCKET, admin trace BUCKET에서 첫 대상은 bucket이 아니라 configured server ALIAS이다.

• mc configuration
• MinIO Client source and quickstart
• MinIO mc command reference
• MinIO Client downloads

• codex:: 2026-08-04 Migrated the existing page to a language head page and expanded installation, aliases, buckets, objects, synchronization, sharing, access control, administration, safety, and compatibility guidance.