MCP 터미널 서버
모델 컨텍스트 프로토콜(MCP)을 구현하는 보안 터미널 실행 서버입니다. 이 서버는 보안 기능 및 리소스 제한을 갖춘 제어된 명령 실행 기능을 제공합니다.
특징
- 명령 실행 : 출력 캡처 및 오류 처리를 통해 셸 명령을 실행합니다.
- 보안 제어 : 허용된 명령을 제한하고 명령 주입을 방지합니다.
- 리소스 제어 :
- MCP 프로토콜 지원 :
- 표준 MCP 메시지 형식
- 역량 광고
- 스트리밍 출력 지원
개발
로컬 설정
지엑스피1
PyPI에 게시
# Build the package
uv pip install build
python -m build
# Upload to PyPI
uv pip install twine
python -m twine upload dist/*
MCP Inspector로 테스트
MCP Inspector 도구를 사용하면 서버 구현을 테스트할 수 있습니다.
# Install inspector
npm install -g @modelcontextprotocol/inspector
# Test server
npx @modelcontextprotocol/inspector python3 src/mcp_terminal/server.py --allowed-commands "python,pip,git,ls,cd"
테스트 실행
# Run all tests
pytest tests/
# Run specific test file
pytest tests/test_terminal.py
# Run with coverage
pytest --cov=mcp_terminal tests/
Claude Desktop과 함께 사용
패키지가 PyPI에 게시되면:
- UV를 설치하세요 (아직 설치되지 않았다면):
- UV를 사용하여 패키지 설치 :
uv pip install mcp-terminal
- Claude Desktop 구성 : Claude Desktop 구성 파일을 편집합니다(일반적으로 macOS에서는
~/Library/Application Support/Claude/claude_desktop_config.json 에 있음):{
"mcpServers": {
"terminal": {
"command": "uv",
"args": [
"pip",
"run",
"mcp-terminal",
"--allowed-commands",
"python,pip,git,ls,cd",
"--timeout-ms",
"30000",
"--max-output-size",
"1048576"
]
}
}
}
프로토콜 구현
서버는 다음 기능을 갖춘 MCP(모델 컨텍스트 프로토콜)를 구현합니다.
기능 광고
{
"protocol": "1.0.0",
"name": "terminal",
"version": "1.1.0",
"capabilities": {
"execute": {
"description": "Execute a terminal command",
"parameters": {
"command": {
"type": "string",
"description": "The command to execute"
}
},
"returns": {
"type": "object",
"properties": {
"exitCode": { "type": "number" },
"stdout": { "type": "string" },
"stderr": { "type": "string" },
"startTime": { "type": "string" },
"endTime": { "type": "string" }
}
}
}
}
}
메시지 형식
요구 :
{
"type": "execute",
"data": {
"command": "echo 'hello world'"
}
}
응답 :
{
"type": "result",
"data": {
"command": "echo 'hello world'",
"exitCode": 0,
"stdout": "hello world\n",
"stderr": "",
"startTime": "2024-01-20T12:34:56.789Z",
"endTime": "2024-01-20T12:34:56.790Z"
}
}
오류 :
{
"type": "error",
"data": {
"message": "command not allowed"
}
}
보안 고려 사항
- 명령 검증 :
- 허용된 명령만 실행할 수 있습니다.
- Shell 운영자는 차단되었습니다.
- 명령 주입 시도가 방지됩니다.
- 자원 보호 :
- 명령 시간 초과로 인해 중단이 방지됩니다.
- 출력 크기 제한으로 메모리 고갈 방지
- 모든 실패 사례에 대한 오류 처리
- 모범 사례 :
- 프로덕션에서는 항상
allowed-commands 설정하세요. - 보수적인 시간 제한 및 크기 제한을 사용하세요
- 명령 실행 로그 모니터링
기여하다
- 저장소를 포크하세요
- 기능 브랜치를 생성합니다(
git checkout -b feature/amazing-feature ) - 변경 사항을 커밋하세요(
git commit -m 'Add some amazing feature' ) - 브랜치에 푸시(
git push origin feature/amazing-feature ) - 풀 리퀘스트 열기
특허
이 프로젝트는 MIT 라이선스에 따라 라이선스가 부여되었습니다. 자세한 내용은 라이선스 파일을 참조하세요.