Claude Code 플러그인 마켓플레이스, 공식 문서에서 직접 확인한 5가지
마켓플레이스 명령어 한 줄이면 설치 끝이라고 알려져 있는데, 막상 써보니 scope를 잘못 잡으면 팀 프로젝트에 플러그인이 아예 안 붙습니다. Anthropic 공식 문서와 실제 사용 흐름을 같이 놓고 보니 생각보다 챙겨야 할 지점이 많았습니다.
💰 평균 일 사용 비용 $6(약 8,700원)
⚡ 재시작 없이 즉시 반영: /reload-plugins
플러그인 마켓플레이스가 뭔지, 먼저 정확히 잡고 갑니다
Claude Code 플러그인 마켓플레이스는 Skills(커스텀 커맨드), Agents(서브에이전트), Hooks(자동 실행 트리거), MCP 서버, LSP 서버를 하나의 패키지로 묶어 명령어 한 줄로 설치·공유할 수 있게 한 구조입니다. Anthropic 공식 문서에 딱 이렇게 나옵니다 — “커스텀 커맨드, MCP, 서브에이전트, 스킬 등을 하나로 패키징해서 쉽게 공유할 수 있게 만든 템플릿”(출처: Claude Code 공식 문서, discover-plugins, 2026.03).
스마트폰 앱 스토어와 비슷한 구조인데, 결정적으로 다른 점이 있습니다. 앱 스토어는 하나지만 Claude Code 마켓플레이스는 Anthropic이 직접 운영하는 공식 마켓플레이스(claude-plugins-official)와 서드파티가 올린 외부 마켓플레이스가 공존합니다. 이 차이가 보안과 업데이트 방식에서 실질적인 차이로 이어집니다.
💡 공식 발표문과 실제 설치 흐름을 같이 놓고 보니, 마켓플레이스는 단순 플러그인 목록이 아니라 신뢰 체계(trust chain)를 구성하는 구조였습니다. 어디서 가져오느냐가 보안 수준을 결정합니다.
Claude Code는 보안을 위해 마켓플레이스 플러그인을 제자리에서 실행하지 않고 로컬 캐시(~/.claude/plugins/cache)에 복사한 뒤 사용합니다. 원본 저장소에서 악성 코드가 추가되더라도 캐시된 버전이 실행되므로 즉각적인 오염을 막는 구조입니다(출처: Claude Code 공식 문서, plugins-reference, 2026.03).
Anthropic 공식 마켓플레이스에서 설치하는 방법
Anthropic이 직접 관리하는 공식 마켓플레이스 이름은 claude-plugins-official입니다. Claude Code 세션 내에서 /plugin을 실행하고 Discover 탭에서 바로 확인할 수 있습니다(출처: Claude Code 공식 문서, discover-plugins, 2026.03).
CLI로 직접 설치할 때는 아래 형식을 씁니다. @claude-plugins-official을 붙이는 게 핵심인데, 생략하면 다른 마켓플레이스에서 동명의 플러그인을 가져올 수 있습니다.
# 공식 마켓플레이스에서 설치 (마켓플레이스 명시 필수)
/plugin install plugin-name@claude-plugins-official
# 서드파티 마켓플레이스 먼저 추가 후 설치
/plugin marketplace add jarrodwatts/claude-hud
/plugin install claude-hud
공식 마켓플레이스에서 제공하는 플러그인에는 Python(pyright-lsp), TypeScript, Rust, Go 등 11개 언어의 LSP 서버가 포함돼 있습니다. 특히 LSP 플러그인을 쓰면 Claude가 파일을 grep으로 뒤지는 대신 언어 서버가 제공하는 정의·참조 정보를 직접 읽어서 토큰 소비 자체가 줄어드는 효과가 있습니다. 단순히 편의 기능이 아니라 비용에 직결됩니다.
공식 마켓플레이스 주요 플러그인 분류
| 분류 | 플러그인 예시 | 주요 기능 |
|---|---|---|
| 코드 인텔리전스 | pyright-lsp, typescript-lsp |
정의·참조 검색, grep 없이 정확한 심벌 탐색 |
| 협업 도구 | commit-commands, pr-review-toolkit |
Git commit 자동화, PR 리뷰 워크플로우 |
| 외부 서비스 MCP | github, slack, sentry |
GitHub 이슈·PR, Slack 알림, 에러 추적 연동 |
| 에이전트 개발 | plugin-dev, agent-sdk-dev |
플러그인·에이전트 직접 제작 지원 |
출처: Claude Code 공식 문서, discover-plugins (2026.03)
scope를 틀리면 팀에서 아무도 못 씁니다
Claude Code 플러그인 설치에는 세 가지 scope가 있습니다 — user(개인 전체 기본값), project(프로젝트 공유), local(로컬 전용, git 제외). 기본값이 user scope라서 명시하지 않으면 내 컴퓨터에만 설치됩니다. 팀원과 같은 플러그인 환경을 만들려면 반드시 --scope project를 붙여야 합니다(출처: Claude Code 공식 문서, plugins-reference, 2026.03).
💡 “왜 나만 플러그인이 작동하지?”라는 팀 내 혼선의 대부분이 scope 미설정에서 옵니다. project scope로 설치하면 .claude/settings.json에 기록돼 git으로 공유됩니다. 이 파일을 커밋하면 팀 전체가 동일한 플러그인 환경을 씁니다.
# user scope (기본값 — 나만 사용)
claude plugin install formatter@my-marketplace
# project scope — 팀 공유용 (.claude/settings.json에 저장)
claude plugin install formatter@my-marketplace --scope project
# local scope — 로컬 전용 (gitignore됨)
claude plugin install formatter@my-marketplace --scope local
scope별 핵심 차이 요약
| scope | 저장 위치 | 팀 공유 | 추천 용도 |
|---|---|---|---|
| user | ~/.claude/settings.json |
❌ 불가 | 개인 작업 환경 |
| project | .claude/settings.json |
✅ git 커밋 | 팀 표준 환경 |
| local | .claude/settings.local.json |
❌ gitignore | 실험적 테스트 |
출처: Claude Code 공식 문서, plugins-reference (2026.03)
managed scope라는 네 번째 옵션도 있는데, 이건 기업 환경에서 관리자가 strictKnownMarketplaces 설정으로 허용된 마켓플레이스만 쓸 수 있도록 통제할 때 씁니다. 개인 사용자가 직접 바꿀 수 없습니다(출처: Claude Code 공식 문서, plugin-marketplaces, 2026.03).
서드파티 마켓플레이스, 편하지만 보안 차이가 있습니다
GitHub 아무 저장소나 /plugin marketplace add owner/repo 형식으로 추가할 수 있습니다. 그러나 공식 문서는 이 부분에서 명확한 주의를 달아뒀습니다 — 서드파티 마켓플레이스 플러그인은 Anthropic이 직접 검증하지 않습니다. 기업 환경에서는 strictKnownMarketplaces 설정으로 특정 출처만 허용하는 방식이 권고됩니다(출처: Claude Code 공식 문서, plugin-marketplaces, 2026.03).
서드파티 마켓플레이스 중 가장 많이 쓰이는 것들이 있는데, 그 중 Claude HUD(jarrodwatts/claude-hud)는 현재 세션 내 컨텍스트 사용량, 실행 중인 도구, 서브에이전트 상태, 할 일 진행률을 터미널 입력창 바로 아래에 실시간으로 표시해 줍니다. Claude Code v1.0.80 이상에서 작동하며, Linux에서는 TMPDIR을 별도 설정해야 설치가 됩니다(출처: fornewchallenge 티스토리, 2026.03.27).
💡 공식 마켓플레이스에 없다고 무조건 못 쓰는 건 아닙니다. 단, npm 패키지 출처, GitHub 저장소 최근 커밋 날짜, 라이선스를 직접 확인하는 습관이 필요합니다. 오픈소스라도 악성 업데이트가 배포된 사례는 있습니다.
서드파티 플러그인은 npm, GitHub, GitLab, Bitbucket, git URL 어느 경로로든 가져올 수 있습니다. Claude Code는 플러그인을 로컬 캐시에 복사한 뒤 실행하므로 원본 저장소가 갑자기 바뀌어도 캐시된 버전이 계속 돌아갑니다. 이 말은 업데이트가 자동으로 반영되지 않는다는 뜻이기도 합니다 — /plugin marketplace update marketplace-name을 직접 실행해야 합니다.
재시작 없이 즉시 반영하는 방법이 따로 있습니다
플러그인을 설치하거나 업데이트하면 Claude Code를 완전히 껐다 켜야 반영된다고 알려져 있습니다. 직접 확인해보니 이건 반만 맞습니다. /reload-plugins 명령어 한 줄로 재시작 없이 즉시 적용됩니다(출처: Claude Code 공식 문서, discover-plugins, 2026.03).
긴 작업 세션 중간에 플러그인을 새로 추가하거나 업데이트했을 때 특히 유용합니다. 세션을 끊으면 컨텍스트가 날아가는 상황에서 재시작 대신 /reload-plugins만 치면 됩니다. 단, LSP 서버 플러그인은 재시작이 필요한 경우가 있습니다 — 공식 문서에서 별도 이유를 밝히지 않았지만, LSP 서버가 별도 프로세스로 뜨는 구조상 세션 레벨 reload만으로는 반영이 안 될 수 있습니다.
💡 플러그인 설치 → /reload-plugins → 즉시 사용 가능. Claude Code를 종료하지 않아도 됩니다. 이 흐름이 공식 문서에 적혀 있는데 기존 가이드에서 빠진 경우가 많았습니다.
플러그인을 비활성화하고 싶을 때도 제거할 필요가 없습니다. /plugin disable plugin-name@marketplace-name으로 일시 정지하고, 필요하면 다시 /plugin enable로 켜면 됩니다. 제거와 달리 데이터는 그대로 유지됩니다.
비용을 잘못 보면 손해 보는 구조가 있습니다
Claude Code 공식 비용 문서에 따르면 개발자 1인당 평균 하루 비용은 $6(약 8,700원)이고, 90%의 사용자는 하루 $12(약 17,400원) 이하입니다(출처: Claude Code 공식 문서, costs, 2026.03). 한 달로 환산하면 평균 약 18만 원 수준인데, Claude Code Max($100/월, 약 14.5만 원 기준)나 Max Tier 2($200/월)와 비교하면 구독 플랜이 더 유리한 경우도 있습니다.
여기서 플러그인이 비용에 영향을 줍니다. LSP 플러그인(pyright-lsp, typescript-lsp 등)을 쓰면 Claude가 파일을 grep으로 탐색하는 대신 언어 서버가 정의·참조 정보를 직접 제공하므로 토큰 소비가 줄어듭니다. 반대로 MCP 서버 플러그인을 과도하게 붙이면 컨텍스트가 늘어납니다 — 공식 문서는 MCP 툴이 전체의 10%를 넘기면 ENABLE_TOOL_SEARCH=auto:5 설정으로 자동 필터링하라고 권고합니다(출처: Claude Code 공식 문서, costs, 2026.03). MCP 툴이 5개 이하일 때만 자동 필터링 없이 전부 노출됩니다.
💡 플러그인을 많이 설치할수록 좋을 것 같지만, MCP 서버 플러그인을 무더기로 붙이면 컨텍스트가 부풀어서 오히려 비용이 올라갑니다. 써야 할 것만 골라서 project scope에 넣는 게 팀 비용 관리에도 낫습니다.
비용 추적은 세션 중 /cost 명령어로 언제든 확인할 수 있습니다. 총 비용, API 실행 시간, 실제 경과 시간, 코드 변경 줄 수가 한 번에 나옵니다. 팀 전체 사용량은 Anthropic 콘솔(platform.claude.com)에서 워크스페이스 단위로 확인합니다.
자주 나오는 질문 5가지
Q1. 플러그인을 설치했는데 Claude Code에서 안 보입니다.
대부분 두 가지 원인입니다. 첫째, /reload-plugins를 실행하지 않았거나, 둘째, scope가 달라서 현재 프로젝트에 플러그인이 로드되지 않은 경우입니다. /plugin에서 Installed 탭을 먼저 확인하고, scope와 마켓플레이스 이름(plugin-name@marketplace-name)이 맞는지 점검하세요. Claude Code 버전이 v1.0.33 미만이면 /plugin 명령어 자체가 없습니다. claude --version으로 버전을 먼저 확인하세요(출처: Claude Code 공식 문서, discover-plugins, 2026.03).
Q2. 플러그인 자동 업데이트는 어떻게 되나요?
Claude Code가 실행될 때 마켓플레이스 플러그인을 자동으로 업데이트합니다. 단, DISABLE_AUTOUPDATER=true를 설정한 경우에는 자동 업데이트가 꺼집니다. 이 환경에서도 플러그인만 별도로 업데이트하고 싶다면 FORCE_AUTOUPDATE_PLUGINS=true를 추가로 설정하면 됩니다(출처: Claude Code 공식 문서, discover-plugins, 2026.03). 수동으로는 /plugin marketplace update marketplace-name을 씁니다.
Q3. Linux에서 플러그인 설치 시 EXDEV 오류가 납니다.
Linux의 /tmp가 별도 파일시스템(tmpfs)으로 마운트된 경우 발생합니다. Claude Code를 실행하기 전에 아래 명령어로 TMPDIR을 설정하세요.
mkdir -p ~/.cache/tmp && TMPDIR=~/.cache/tmp claude
이 설정 이후 플러그인 설치를 진행하면 오류가 사라집니다(출처: fornewchallenge 티스토리, 2026.03.27).
Q4. 내가 만든 플러그인을 팀에 배포하려면 어떻게 하나요?
팀 배포에는 세 가지 방법이 있습니다. ① GitHub 저장소에 .claude-plugin/marketplace.json을 만들고 /plugin marketplace add owner/repo로 공유. ② 팀 설정 파일(.claude/settings.json)의 extraKnownMarketplaces에 마켓플레이스를 명시하고 git으로 공유. ③ 기업 환경이라면 strictKnownMarketplaces로 허용 출처를 통제합니다. 제일 간단한 건 ① 방법이고, ②는 팀원이 별도로 마켓플레이스를 추가할 필요 없이 저장소를 clone하면 자동으로 설정됩니다(출처: Claude Code 공식 문서, plugin-marketplaces, 2026.03).
Q5. 플러그인을 삭제하면 플러그인 데이터(캐시)도 사라지나요?
기본적으로 /plugin uninstall을 실행하면 플러그인 설정 등록은 해제되지만, 플러그인이 저장해 둔 데이터(~/.claude/plugins/data/)는 삭제되지 않습니다. 데이터까지 완전히 지우려면 --keep-data 플래그 없이 제거한 뒤 해당 폴더를 직접 삭제해야 합니다. --keep-data를 명시하면 삭제 후에도 데이터가 유지됩니다(출처: Claude Code 공식 문서, plugins-reference, 2026.03).
마치며 — 플러그인은 많이 깔수록 좋을까요?
솔직히 말하면, 아닙니다. 공식 문서를 처음부터 끝까지 읽고 나서 바뀐 생각이 이겁니다. LSP 플러그인 몇 개는 분명히 비용을 줄여주고, 팀 협업용 커밋·PR 플러그인은 반복 작업을 덜어줍니다. 그런데 MCP 서버 플러그인을 무더기로 붙이면 컨텍스트가 늘어나서 오히려 역효과입니다.
scope 설정 하나 틀리면 팀 전체가 제각각 환경에서 일하게 됩니다. 공식 마켓플레이스(claude-plugins-official) 먼저 쓰고, 서드파티는 저장소 라이선스와 최근 커밋을 확인한 뒤 추가하는 게 맞습니다. /reload-plugins 하나로 재시작 없이 반영된다는 것도, 플러그인 데이터가 uninstall해도 남는다는 것도 — 직접 문서 읽기 전에는 몰랐던 것들입니다. 지금 쓰는 Claude Code가 최신 버전인지(claude --version), v1.0.33 이상인지 먼저 확인하고 시작하는 걸 권합니다.
📚 본 포스팅 참고 자료
- Claude Code 공식 문서 — 플러그인 마켓플레이스 발견 및 설치: https://code.claude.com/docs/ko/discover-plugins
- Claude Code 공식 문서 — 플러그인 참조(manifest·CLI): https://code.claude.com/docs/ko/plugins-reference
- Claude Code 공식 문서 — 마켓플레이스 생성 및 배포: https://code.claude.com/docs/ko/plugin-marketplaces
- Claude Code 공식 문서 — 비용 관리: https://code.claude.com/docs/ko/costs
- Claude HUD 플러그인 GitHub: https://github.com/jarrodwatts/claude-hud
본 포스팅은 2026년 3월 28일 기준 Claude Code v1.0.80 이상을 대상으로 작성됐습니다. 본 포스팅 작성 이후 서비스 정책·UI·기능이 변경될 수 있습니다. 플러그인 보안 및 비용과 관련한 최신 정보는 Claude Code 공식 문서에서 직접 확인하세요.
댓글 남기기