yotsuda/PowerShell.MCP

보안 경고: 이 모듈은 시스템에 대한 완전한 PowerShell 접근 권한을 제공합니다. 악의적인 사용은 심각한 손상을 초래할 수 있습니다. 책임감 있게, 그리고 신뢰할 수 있는 환경에서만 사용하십시오.**

범용 MCP 서버—단 한 번의 설치로 AI가 10,000개 이상의 PowerShell 모듈과 모든 CLI 도구에 접근할 수 있습니다.

PowerShell.MCP는 단일 MCP 서버를 통해 AI 비서와 전체 PowerShell 생태계를 연결합니다. 사용자와 AI가 동일한 PowerShell 콘솔에서 협업하며, AI가 실행하는 모든 명령어는 실행되는 대로 표시되고, 이를 기록하는 트랜스크립트도 작성할 수 있습니다 (AI 세션 감사 참조).**

대신 bash, 언어 REPL, SQL 콘솔 또는 디버거가 필요하신가요? PowerShell 7을 설치할 수 없거나, 다른 셸(bash, cmd, zsh), 언어 REPL(python, node, racket, lua 등), SQL 콘솔(sqlite3 등), 또는 언어 디버거(pdb, jdb, perldb)를 사용하고 싶다면 ripple을 확인해 보세요. 이는 동일한 공유 콘솔 개념을 모든 REPL에 일반화하여, 통합된 ConPTY 기반의 콘솔들이 나란히 실행되는 방식입니다.**

PowerShell 생태계로 가는 범용 게이트웨이.

PowerShell.MCP는 서비스별 MCP 서버와는 다른 접근 방식을 취합니다. 개별 서비스에 대한 선별된 도구를 제공하기보다는, AI 비서에게 PowerShell 자체에 직접적인 접근 권한을 부여하여 전문가들이 매일 사용하는 것과 동일한 모듈 및 CLI 도구를 사용할 수 있게 합니다.

이것은 다음을 의미합니다:

하나의 MCP 서버가 여러 개를 대체함— 각 서비스마다 별도의 서버가 필요하지 않음즉각적인 접근성— 전용 MCP 서버를 기다릴 필요 없이 PowerShell Gallery의 10,000개 이상의 모듈에 즉시 접근 가능크로스-서비스 워크플로우— 단일 파이프라인에서 여러 서비스를 결합API 탐색— 프로덕션 코드를 작성하기 전에 즉각적인 피드백으로 API 동작을 프로토타입 및 검증자가 진화하는 기능— AI와 사용자가 모두 실행할 수 있는 PowerShell 스크립트를 작성하여 가능한 범위를 지속적으로 확장업계 표준 기술— 학습한 명령어가 자신의 업무에 직접 적용 가능

예시: PowerShell 파이프라인 처리

PowerShell.MCP는 기존 MCP 설정을 보완하여 유연하고 범용적인 기반을 제공합니다.

🖥️ 다중 클라이언트 아키텍처 (Multi-Client Architecture)

• 각 클라이언트 인스턴스는 전용 콘솔을 가집니다 — 여러 Claude Code 세션을 병렬로 실행할 수 있습니다.
• 리소스 충돌 없이 안전하게 병렬 작업이 가능합니다.
• 쉽게 식별할 수 있도록 고유한 창 제목(예: "#12345 Taxi")을 제공합니다.
  Get-MCPOwner

cmdlet은 현재 콘솔의 소유 클라이언트를 보여줍니다.

🤝 공유 콘솔 경험 (Shared Console Experience)

• 사용자와 AI가 동일한 PowerShell 세션에서 완전한 투명성을 가지고 협업합니다.
• AI가 실행하는 모든 명령이 실시간으로 콘솔에 표시됩니다.
• 대화형 프롬프트에 직접 콘솔에서 응답할 수 있습니다.
• 짧은 명령어는 Windows의 콘솔 기록에 추가되어, AI가 작업하는 것을 보며 배울 수 있습니다.

🔄 영속적인 세션 상태 (Persistent Session State)

• 한 번 인증하면 유지됩니다: Azure, AWS, Microsoft 365 등
• 모듈, 변수 및 함수는 명령 전반에 걸쳐 지속됩니다.
• 재초기화 오버헤드가 없습니다.

🌐 범용 접근성 (Universal Access)

• PowerShell Gallery: Az, AWS.Tools, Microsoft.Graph를 포함한 10,000개 이상의 모듈
• 모든 CLI 도구: git, docker, kubectl, terraform, gh, az cli, aws cli
• AI가 Get-Help를 통해 구문을 자동으로 학습

🔗 파이프라인 조합성 (Pipeline Composability)

• 자연어로 원하는 바를 설명하면—AI가 최적의 파이프라인을 구성합니다.

• "가장 큰 로그 상위 5개" →
  Get-ChildItem *.log | Sort-Object Length -Descending | Select-Object -First 5

• 모든 서비스에 걸쳐 명령어를 연결할 수 있습니다.

⚡ 즉시 실행 (Instant Execution)

• 기존 콘솔에서 명령어가 즉시 실행됩니다.
• 명령어당 프로세스 시작 오버헤드가 없습니다.
• 실시간 스트리밍 출력을 제공합니다.

🔐 엔터프라이즈급 보안 (Enterprise-Ready Security)

• 로컬 전용 명명된 파이프 통신—네트워크 노출 없음
• 모든 명령어가 가시화되며, Start-Transcript 또는 스크립트 블록 로깅(AI 세션 감사)으로 기록 가능합니다. 기존 보안 정책과 통합됩니다.

🔒 비밀 정보는 AI가 아닌 사용자에게 머무릅니다

• 대화형 프롬프트(Read-Host -AsSecureString, Get-Credential, MFA 코드)를 통해 입력을 AI로부터 숨깁니다. 코드 서명, gpg, ssh-add, sudo, 클라우드 CLI MFA 등을 위해 암호 구문을 입력합니다—키스트로크는 프로그램으로 전송되며 절대 AI의 출력 스트림으로 가지 않습니다. AI가 워크플로우를 오케스트레이션("빌드, 태그 서명, 푸시")하고, 사용자가 적절한 순간에 비밀 정보를 공급합니다.
• AI가 비밀 정보를 어떻게든 주입해야 하는 stdin-piped MCP 셸에서는 불가능합니다.

최소한의 복잡성으로 최대의 유연성을 제공하는 여섯 가지 도구:

모든 플랫폼에 필요한 것:

• PowerShell 7.4 이상 (설치 가이드)
• Claude Desktop, Claude Code 또는 모든 MCP 클라이언트

Win + R을 누르고,
pwsh를 입력한 다음,
Enter를 누릅니다.

Install-PSResource PowerShell.MCP

Claude Code용:

Register-PwshToClaudeCode

이후 Claude Code의 내장 Bash 및 PowerShell 도구를 비활성화할지 묻는 메시지가 나타나며, 모든 명령이 볼 수 있는 콘솔에서 실행되도록 합니다. -DisableBuiltInShellTools를 사용하거나
-KeepBuiltInShellTools를 사용하여 질문 없이 답변합니다.

Claude Desktop용:

Register-PwshToClaudeDesktop

기타 MCP 클라이언트용: Get-MCPProxyPath -Escape를 실행하여 JSON 이스케이프된 실행 파일 경로를 얻은 다음, 이를 수동으로 클라이언트의 설정 파일에 추가합니다.

Linux 설정

# Ubuntu/Debian
sudo apt-get update
sudo apt-get install -y wget apt-transport-https software-properties-common
...

# PowerShell (pwsh)에서 실행
Install-PSResource PowerShell.MCP
chmod +x "$(Get-MCPProxyPath)"

Claude Code용:

Register-PwshToClaudeCode

이후 Claude Code의 내장 Bash 및 PowerShell 도구를 비활성화할지 묻는 메시지가 나타나며, 모든 명령이 볼 수 있는 콘솔에서 실행되도록 합니다. -DisableBuiltInShellTools를 사용하거나
-KeepBuiltInShellTools를 사용하여 질문 없이 답변합니다.

Claude Desktop용:

Register-PwshToClaudeDesktop

기타 MCP 클라이언트용: Get-MCPProxyPath -Escape를 실행하여 JSON 이스케이프된 실행 파일 경로를 얻은 다음, 이를 수동으로 클라이언트의 설정 파일에 추가합니다.

macOS 설정

brew install --cask powershell
# 캐시가 사용할 수 없는 경우, GitHub Release에서 설치합니다 (Intel Mac의 경우 osx-arm64 대신 osx-x64를 사용하세요):
# curl -sSL -o /tmp/powershell.tar.gz https://github.com/PowerShell/PowerShell/releases/download/v7.5.4/powershell-7.5.4-osx-arm64.tar.gz
...

# PowerShell (pwsh)에서 실행
Install-PSResource PowerShell.MCP
chmod +x "$(Get-MCPProxyPath)"

Claude Code용:

Register-PwshToClaudeCode

그러면 Claude Code의 내장 Bash 및 PowerShell 도구를 비활성화할지 묻습니다. 이렇게 하면 모든 명령이 볼 수 있는 콘솔에서 실행됩니다. -DisableBuiltInShellTools

또는 -KeepBuiltInShellTools

을 물어보지 않고 답변합니다.

Claude Desktop의 경우:

Register-PwshToClaudeDesktop

다른 MCP 클라이언트의 경우: Get-MCPProxyPath -Escape를 실행하여 JSON 이스케이프된 실행 파일 경로를 얻은 다음, 이를 수동으로 클라이언트의 구성 파일에 추가합니다.

설치된 모든 버전은 자체 폴더에 존재하므로, MCP 클라이언트가 시작하는 프록시 경로는 업데이트할 때마다 변경됩니다. 따라서 업데이트 후에는 다시 등록해야 합니다. 그렇지 않으면 클라이언트는 이전 버전의 프록시를 계속 시작하고 명령이 "PowerShell.MCP.Proxy version is outdated" 오류와 함께 실패합니다.

새로운 PowerShell 7 창(PowerShell.MCP 콘솔 중 하나가 아닌)을 열고 다음을 실행합니다:

Update-PSResource PowerShell.MCP

이미 PowerShell.MCP를 로드한 창은 이전 버전을 유지하므로, 방금 설치된 버전을 로드하는 새 창을 하나 더 여십시오:

chmod +x "$(Get-MCPProxyPath)" # Linux / macOS 전용: 새로운 프록시는 다시 실행 권한이 필요합니다
Register-PwshToClaudeCode # Claude Code
Register-PwshToClaudeDesktop # Claude Desktop

둘 다 기존 pwsh 항목을 대체하며, --no-profile과 같이 이미 설정된 인수와 환경 변수는 유지합니다. 다른 MCP 클라이언트의 경우: 구성 파일의 경로를 Get-MCPProxyPath -Escape의 출력으로 대체하십시오.

PowerShell.MCP 콘솔 창(예: #12345 Taxi로 제목이 지정됨)을 닫으십시오. (각각 시작된 버전을 계속 실행합니다.) 그런 다음 MCP 클라이언트를 종료했다가 다시 시작하십시오.

설치된 내용을 확인하고, 더 이상 사용하지 않는 버전이 있다면 제거하려면:

Get-InstalledPSResource PowerShell.MCP
Uninstall-PSResource PowerShell.MCP -Version <old version>

기본적으로 프록시가 시작하는 모든 콘솔은 사용자 PowerShell $PROFILE (프롬프트, 별칭, PSReadLine, 테마)을 로드합니다. 이는 단순한 자동화 대상이 아니라 실제 대화형 셸입니다. --no-profile을 전달하십시오.

시작할 때 -NoProfile을 사용합니다.

대신 더 빠른 시작과 깨끗하고 결정론적인 환경을 위해 사용합니다.

Claude Code:

claude mcp remove pwsh -s user # pwsh가 이미 등록된 경우: 'claude mcp add'는 기존 이름을 거부함
claude mcp add pwsh -s user -- "$(Get-MCPProxyPath)" --no-profile

이후부터 Register-PwshToClaudeCode는 업데이트 후 재등록할 때도 플래그를 유지합니다.

Claude Desktop / 기타 MCP 클라이언트: pwsh 항목에 --no-profile을 포함하는 args 배열을 구성 파일에 추가합니다 (Register-PwshToClaudeDesktop은 재등록 시에도 이를 유지합니다):

"mcpServers": {
"pwsh": {
"command": "...PowerShell.MCP.Proxy.exe",
...

헤드리스(headless) / CI 런처는 이 플래그와 관계없이 항상 -NoProfile을 사용합니다.

콘솔이 쌓일 경우, AI나 사용자 모두 10분 동안 사용하지 않은 콘솔은 경고 메시지를 출력한 후 60초 후에 스스로 종료됩니다. 각 세션의 가장 최근에 사용된 콘솔은 항상 유지되며, 바쁘거나 프롬프트에서 대기 중이고 아직 수집되지 않은 출력을 보유하고 있거나 프롬프트에 텍스트가 입력된 콘솔은 절대 종료되지 않습니다. 무언가를 타이핑하거나 AI 명령을 실행하면 보류 중인 종료를 취소합니다. 서브 에이전트(is_subagent=true)가 시작한 콘솔은 유지되지 않습니다: 유휴 상태가 되면 다른 콘솔과 마찬가지로 종료되는데, 완료된 서브 에이전트는 다시 돌아오지 않기 때문입니다.

이 변수들을 MCP 클라이언트의 env 블록에 설정하는 것이 아니라 사용자 또는 시스템 환경 변수로 설정해야 합니다 (Windows: 시스템 속성 → 환경 변수, 또는 setx; macOS / Linux: 로그인 셸 프로필). 각 콘솔은 프록시의 자식이 아니라 새로운 터미널 창이므로, 프록시만을 위해 설정된 변수는 일반적으로 해당 콘솔에 도달하지 못합니다.

블로킹 호출은 MCP 클라이언트가 실제로 대기하는 시간으로 제한됩니다: Claude Code의 경우 170초, 그리고 다른 모든 클라이언트의 경우 50초입니다. 제한에 도달해도 아무것도 손실되지 않습니다. 명령어는 계속 실행되며, 결과는 다음 도구 호출과 함께 도착합니다. 클라이언트가 50초 이상 대기해야 하는 경우, POWERSHELL_MCP_TIMEOUT_CEILING으로 제한을 높이세요

(최대 170초). 이 값은 프록시에서 읽으므로 MCP 클라이언트의 env에 설정하세요

block:

"mcpServers": {
"pwsh": {
"command": "...PowerShell.MCP.Proxy.exe",
...

Claude Code CLI를 사용하는 경우, 다음 명령어로 전달합니다.
claude mcp add에 -e POWERSHELL_MCP_TIMEOUT_CEILING=120

; Register-PwshToClaudeCode

그리고 Register-PwshToClaudeDesktop

재등록할 때 유지하세요.

PowerShell.MCP의 기능을 경험해 보세요: