MCP 터미널 서버

모델 컨텍스트 프로토콜(MCP)을 구현하는 보안 터미널 실행 서버입니다. 이 서버는 보안 기능 및 리소스 제한을 갖춘 제어된 명령 실행 기능을 제공합니다.

특징

명령 실행 : 출력 캡처 및 오류 처리를 통해 셸 명령을 실행합니다.
보안 제어 : 허용된 명령을 제한하고 명령 주입을 방지합니다.
리소스 제어 :
- 명령 시간 초과
- 최대 출력 크기 제한
MCP 프로토콜 지원 :
- 표준 MCP 메시지 형식
- 역량 광고
- 스트리밍 출력 지원

Related MCP server: Terminal Controller for 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를 설치하세요 (아직 설치되지 않았다면):
```
pip install 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 설정하세요.
- 보수적인 시간 제한 및 크기 제한을 사용하세요
- 명령 실행 로그 모니터링