junis

AI 에이전트가 내 컴퓨터를 완전 제어할 수 있게 해주는 로컬 MCP 도구 서버입니다. 셸 명령 실행, 파일 관리, 브라우저 자동화, 노트북 편집, 화면/카메라 캡처 등 28개 도구를 제공합니다.

특징

• 제로 설정 로컬 모드 — npx junis --local 한 줄이면 바로 사용 가능
• 클라우드 릴레이 모드 — wss://api.junis.ai를 통해 원격 디바이스 제어
• 파일 & 셸 도구 — 읽기, 쓰기, 검색, 명령 실행, 프로세스 관리
• 브라우저 자동화 — Playwright 기반 웹 탐색, 클릭, 입력, 스크린샷, PDF 저장
• 노트북 도구 — Jupyter 노트북 셀 읽기, 수정, 추가, 삭제, 실행
• 디바이스 도구 — 화면 캡처, 카메라, 알림, 클립보드, 녹화, 위치, 오디오
• MCP 호환 — Claude Code, Claude Desktop 등 모든 MCP 클라이언트와 연동
• TypeScript — @modelcontextprotocol/sdk 기반

설치 및 실행

로컬 모드 (계정 불필요)

npx junis --local

http://localhost:3000/mcp에 MCP 서버가 시작됩니다. MCP 클라이언트에서 이 주소를 지정하면 바로 사용할 수 있습니다.

클라우드 모드

npx junis

최초 실행 시 브라우저가 열려 OAuth 로그인을 진행합니다. 인증 후 디바이스가 wss://api.junis.ai에 연결되어 원격 AI 에이전트 세션을 받을 수 있습니다. 백그라운드 데몬으로 실행되며 부팅 시 자동 시작됩니다.

포트 변경

npx junis --local --port 8080

제공 도구 목록

FilesystemTools (8개)

| 도구 | 설명 | |------|------| | execute_command | 터미널 명령 실행 (타임아웃, 백그라운드 실행 지원) | | read_file | 파일 읽기 (utf-8, base64 인코딩 지원) | | write_file | 파일 쓰기/생성 (상위 디렉토리 자동 생성) | | edit_block | 파일의 특정 텍스트 블록을 교체 (diff 기반 부분 수정) | | list_directory | 디렉토리 내 파일/폴더 목록 조회 | | search_code | 코드/텍스트 패턴 검색 (ripgrep 우선, fallback으로 glob 검색) | | list_processes | 실행 중인 프로세스 목록 (CPU 사용률 순) | | kill_process | 프로세스 종료 (SIGTERM 후 3초 대기, 미종료 시 SIGKILL 자동 적용) |

BrowserTools (7개)

Playwright 설치 필요: npx playwright install chromium 미설치 시 브라우저 도구 호출 시 경고 메시지만 출력되며 서버가 중단되지 않습니다.

| 도구 | 설명 | |------|------| | browser_navigate | URL로 이동 | | browser_click | CSS 선택자로 요소 클릭 | | browser_type | 텍스트 입력 (기존 내용 삭제 후 입력 옵션) | | browser_screenshot | 현재 페이지 스크린샷 (파일 저장 또는 base64 반환) | | browser_snapshot | 페이지 접근성 트리(aria snapshot) 조회 | | browser_evaluate | 페이지 내 JavaScript 실행 | | browser_pdf | 현재 페이지를 PDF로 저장 |

NotebookTools (5개)

Jupyter 설치 필요: pip install jupyter

| 도구 | 설명 | |------|------| | notebook_read | .ipynb 노트북 셀 목록 및 내용 조회 | | notebook_edit_cell | 특정 셀 소스 코드 수정 | | notebook_add_cell | 새 셀 추가 (code/markdown, 위치 지정 가능) | | notebook_delete_cell | 특정 셀 삭제 | | notebook_execute | 노트북 전체 실행 (nbconvert --execute) |

DeviceTools (8개)

| 도구 | 설명 | |------|------| | screen_capture | 화면 스크린샷 (macOS: screencapture, Linux: scrot) | | camera_capture | 카메라 사진 촬영 (macOS: imagesnap, Linux: fswebcam) | | notification_send | OS 알림 전송 | | clipboard_read | 클립보드 내용 읽기 | | clipboard_write | 클립보드에 텍스트 쓰기 | | screen_record | 화면 녹화 시작/중지 (macOS: screencapture -v, 기타: ffmpeg) | | location_get | 현재 위치 조회 (macOS: CoreLocation, fallback: IP 기반) | | audio_play | 오디오 파일 재생 (macOS: afplay, 기타: ffplay) |

CLI 명령어

Usage: npx junis [options] [command]

| 명령어 | 설명 | |--------|------| | start (기본) | Junis 에이전트 시작. 인증 후 백그라운드 데몬으로 실행 | | stop | 백그라운드 서비스 중지 및 자동시작 해제 | | logout | 저장된 인증 정보 삭제 | | status | 현재 연결 및 디바이스 상태 확인 |

옵션

| 옵션 | 설명 | |------|------| | --local | 클라우드 연결 없이 로컬 MCP 서버만 실행 | | --port <number> | 로컬 MCP 서버 포트 (기본: 3000) | | --reset | 기존 인증 초기화 후 재로그인 |

사용 예시

# 로컬 MCP 서버 실행 (기본 포트)
npx junis --local

# 로컬 MCP 서버 실행 (포트 지정)
npx junis --local --port 8080

# 클라우드 모드로 시작 (최초 실행 시 인증)
npx junis

# 인증 초기화 후 재로그인
npx junis --reset

# 백그라운드 서비스 중지
npx junis stop

# 연결 상태 확인
npx junis status

# 로그아웃
npx junis logout

MCP Client Integration

To use junis with Claude Code, Claude Desktop, Codex, or any other MCP client, add the following to your MCP config:

{
  "mcpServers": {
    "junis": {
      "command": "npx",
      "args": ["-y", "junis", "--stdio"]
    }
  }
}

For Claude Code, you can also register via CLI:

claude mcp add junis -- npx -y junis --stdio

No separate server process is needed — the MCP client will launch junis automatically.

알려진 제한사항

• camera_capture (macOS 데몬 모드): macOS에서 데몬(백그라운드) 모드로 실행 시 카메라에 접근하려면 시스템 설정 > 개인정보 보호 및 보안 > 카메라에서 node에 권한을 직접 부여해야 합니다.
• screen_capture (macOS): 화면 녹화 권한이 필요합니다. 시스템 설정 > 개인정보 보호 및 보안 > 화면 및 시스템 오디오 녹음에서 터미널 앱에 권한을 부여하세요.
• browser 도구: Playwright가 설치되어 있지 않으면 브라우저 도구 호출 시 경고만 출력됩니다. npx playwright install chromium으로 설치하세요.
• notebook 도구: Jupyter가 설치되어 있지 않으면 노트북 실행(notebook_execute)이 실패합니다. pip install jupyter로 설치하세요.
• location_get: macOS에서 CoreLocationCLI가 없으면 IP 기반 위치 추정으로 자동 전환됩니다 (정확도 낮음).

환경 변수

| 변수 | 기본값 | 설명 | |------|--------|------| | JUNIS_API_URL | https://api.junis.ai | REST API 기본 URL | | JUNIS_WS_URL | wss://api.junis.ai | WebSocket 릴레이 URL | | JUNIS_WEB_URL | https://junis.ai | 웹 UI URL (OAuth 시 사용) |

요구 사항

• Node.js >= 18
• (선택) Playwright — 브라우저 도구: npx playwright install chromium
• (선택) Jupyter — 노트북 도구: pip install jupyter
• (선택) imagesnap — macOS 카메라 캡처: brew install imagesnap

라이선스

MIT