N Lobby CLI

참고: 개발자는 이 도구를 사용하여 발생할 수 있는 어떠한 손해에 대해서도 책임을 지지 않습니다. 이 소프트웨어는 교육 목적으로 개발되었으며 작동이 보장되지 않습니다.

N Lobby 학교 포털 데이터에 액세스하기 위한 듀얼 모드 CLI 및 Model Context Protocol (MCP) 서버입니다. 터미널에서 nlobby로 대화형으로 사용하거나, nlobby serve를 통해 MCP 서버로서 AI 어시스턴트에 연결할 수 있습니다.

기능

CLI 모드: 터미널에서 직접 N Lobby 데이터(뉴스, 일정, 강의, 프로필 등)에 액세스
MCP 모드: Claude, Cursor 및 기타 MCP 지원 AI 어시스턴트와 호환되는 완전한 MCP 서버
브라우저 기반 인증: 자동화된 Puppeteer 브라우저 창을 통한 대화형 로그인
세션 유지: CLI 모드는 원활한 후속 사용을 위해 쿠키를 ~/.nlobby/session에 저장
학교 정보 액세스: 공지사항, 일정 및 학습 자료 검색
필수 과목 관리: 필수 과목 정보 및 학업 데이터 액세스
다양한 캘린더 유형: 개인 및 학교 캘린더 모두 지원
사용자 역할 지원: 학생, 학부모, 교직원을 위한 다양한 액세스 수준

Related MCP server: MCP Server Sample

설치

옵션 1: npm에서 설치 (권장)

npm install -g nlobby-cli

옵션 2: 개발용 설치

저장소 복제:

git clone https://github.com/minagishl/nlobby-cli.git
cd nlobby-cli

의존성 설치:

pnpm install

프로젝트 빌드:

pnpm run build

구성

기본값을 재정의해야 하는 경우 .env 파일을 생성하세요 (선택 사항):

NLOBBY_BASE_URL=https://nlobby.nnn.ed.jp
MCP_SERVER_NAME=nlobby-cli
MCP_SERVER_VERSION=1.0.0

CLI 사용법

인증

# Interactive browser login (recommended)
nlobby login

# Set cookies manually
nlobby cookies set "__Secure-next-auth.session-token=ey...;"

# Check current authentication status
nlobby cookies check

뉴스

# List latest news (default: 10, newest first)
nlobby news

# Filter and sort
nlobby news --limit 20 --category お知らせ --sort oldest --unread

# Show full article
nlobby news show 980

# Download the first attachment to /tmp
nlobby news download 980 --index 1 --output-dir /tmp

# Mark as read
nlobby news read 980

일정 및 캘린더

# Today's schedule
nlobby schedule

# Specific date
nlobby schedule 2026-04-01

# This week's personal calendar
nlobby calendar

# School calendar for a date range
nlobby calendar --type school --from 2026-04-01 --to 2026-04-07

강의

# All required courses
nlobby courses

# Filter by grade / semester
nlobby courses --grade 2 --semester 2025

프로필 및 건강

nlobby profile
nlobby health

MCP 서버

# Start MCP server (stdio transport)
nlobby serve
# or
nlobby mcp

모든 명령어는 --json을 지원하여 포맷된 텍스트 대신 원시 JSON을 출력합니다.

MCP 사용법

Cursor IDE 설정

Install MCP Server

Cursor 설정(~/.cursor/config.json)에 다음을 추가하세요:

{
  "mcpServers": {
    "nlobby": {
      "command": "npx",
      "args": ["-y", "nlobby-cli", "serve"],
      "env": {
        "NLOBBY_BASE_URL": "https://nlobby.nnn.ed.jp"
      }
    }
  }
}

Claude Desktop 설정

Claude Desktop 설정(~/Library/Application Support/Claude/claude_desktop_config.json, macOS 기준)에 추가하세요:

{
  "mcpServers": {
    "nlobby": {
      "command": "npx",
      "args": ["-y", "nlobby-cli", "serve"],
      "env": {
        "NLOBBY_BASE_URL": "https://nlobby.nnn.ed.jp"
      }
    }
  }
}

기타 MCP 클라이언트

MCP 호환 클라이언트의 경우 다음을 사용하세요:

명령어: nlobby serve (전역 설치 시) 또는 node /path/to/dist/index.js serve
프로토콜: stdio
환경 변수: 구성 섹션에 나열된 선택적 환경 변수

MCP 리소스

URI	설명
`nlobby://news`	학교 뉴스 및 공지사항
`nlobby://schedule`	일일 수업 일정 및 이벤트
`nlobby://required-courses`	필수 과목 및 학업 정보
`nlobby://user-profile`	현재 사용자 정보

MCP 도구

인증

도구	설명
`interactive_login`	수동 로그인을 위한 브라우저 열기 (권장)
`login_help`	개인화된 로그인 도움말 및 문제 해결
`set_cookies`	수동으로 인증 쿠키 설정
`check_cookies`	인증 쿠키 상태 확인
`verify_authentication`	모든 클라이언트의 인증 상태 확인

뉴스

도구	주요 매개변수	설명
`get_news`	`category?` `limit?` `sort?`	필터링을 통한 학교 뉴스 검색
`get_news_detail`	`newsId` `markAsRead?`	특정 기사에 대한 전체 세부 정보
`mark_news_as_read`	`ids` (배열)	기사를 읽음으로 표시
`get_unread_news_info`		읽지 않은 개수 및 중요 뉴스 플래그

일정 및 캘린더

도구	주요 매개변수	설명
`get_schedule`	`date?`	특정 날짜의 일정 (YYYY-MM-DD)
`get_calendar_events`	`calendar_type?` `from_date?` `to_date?` `period?`	캘린더 이벤트 (개인/학교)
`test_calendar_endpoints`	`from_date?` `to_date?`	두 캘린더 엔드포인트 테스트
`get_calendar_filters`		Lobby 캘린더 필터 정의

강의 및 시험

도구	주요 매개변수	설명
`get_required_courses`	`grade?` `semester?` `category?`	진행 상황 추적을 포함한 필수 과목
`check_exam_day`	`date?`	특정 날짜가 시험일인지 확인
`finish_exam_day_mode`		시험일 모드 종료
`get_exam_otp`		시험용 일회용 비밀번호 가져오기

계정 및 탐색

도구	설명
`get_account_info`	Next.js 페이지에서 계정 정보 추출
`get_student_card_screenshot`	학생증 스크린샷 캡처
`update_last_access`	마지막 액세스 타임스탬프 업데이트
`get_navigation_menus`	메인 탐색 메뉴 목록
`get_notifications`	알림 메시지
`get_user_interests`	사용자 관심사 태그 (선택적 아이콘 데이터 포함)
`get_interest_weights`	관심사 가중치 척도 정의

디버깅

도구	주요 매개변수	설명
`health_check`		N Lobby API 연결 테스트
`debug_connection`	`endpoint?`	상세 연결 디버깅
`test_page_content`	`endpoint?` `length?`	페이지 콘텐츠 검색 테스트
`test_trpc_endpoint`	`method` `params?`	특정 tRPC 엔드포인트 테스트

인증 흐름

방법 1: 대화형 브라우저 로그인 (권장)

CLI:

nlobby login

MCP 도구: interactive_login

브라우저 창이 자동으로 열립니다. N Lobby 로그인을 완료하면 쿠키가 추출되어 저장됩니다.

방법 2: 수동 쿠키 설정

웹 브라우저에서 N Lobby에 로그인합니다.
개발자 도구 → 애플리케이션 / 저장소 → 쿠키를 엽니다.
모든 쿠키를 문자열로 복사합니다.

CLI:

nlobby cookies set "__Secure-next-auth.session-token=ey...;"

MCP 도구: set_cookies cookies="__Secure-next-auth.session-token=ey...;"

사용자 유형

서버는 이메일 도메인을 기반으로 세 가지 사용자 유형을 지원합니다:

유형	이메일 도메인
학생	`@nnn.ed.jp`
교직원	`@nnn.ac.jp`
학부모	기타 등록된 이메일

프로젝트 구조

src/
├── index.ts              # Entry point — CLI vs MCP mode detection
├── config.ts             # Configuration management
├── logger.ts             # Logging utilities
├── trpc-client.ts        # tRPC client for API calls
├── types.ts              # TypeScript type definitions
├── api/
│   ├── index.ts          # NLobbyApi facade + session persistence
│   ├── context.ts        # ApiContext interface
│   ├── shared.ts         # Shared utilities (fetchRenderedHtml, …)
│   ├── news.ts           # News functions
│   ├── schedule.ts       # Schedule / calendar functions
│   ├── courses.ts        # Course / exam functions
│   ├── account.ts        # Account info / student card functions
│   ├── navigation.ts     # Navigation / notification / interest functions
│   └── health.ts         # Health check / debug functions
├── auth/
│   ├── browser.ts        # Puppeteer browser authentication
│   ├── nextauth.ts       # NextAuth.js session handling
│   └── credentials.ts    # Credential validation and guidance
├── cli/
│   ├── index.ts          # Commander program wiring
│   ├── commands/         # login, news, schedule, courses, profile, health, serve
│   └── formatters/       # Human-readable output formatters
└── mcp/
    └── server.ts         # MCP server (28 tools, 4 resources)

개발

스크립트

pnpm run build   # Build (esbuild bundle + tsc type declarations)
pnpm run dev     # Watch mode
pnpm run start   # Start MCP server
pnpm run lint    # Lint
pnpm run format  # Format

보안 참고 사항

CLI 쿠키는 ~/.nlobby/session에 저장됩니다 (일반 텍스트 — 적절히 보호하세요).
MCP 모드는 모든 인증 토큰을 메모리에만 보관합니다.
브라우저 자동화는 데이터 스크래핑이 아닌 인증 목적으로만 사용됩니다.
민감한 데이터는 기록되지 않습니다.

라이선스

이 프로젝트는 MIT 라이선스에 따라 라이선스가 부여됩니다. 자세한 내용은 LICENSE 파일을 참조하세요.

N Lobby MCP Server

N Lobby CLI

기능

설치

옵션 1: npm에서 설치 (권장)

옵션 2: 개발용 설치

구성

CLI 사용법

인증

뉴스

일정 및 캘린더

강의

프로필 및 건강

MCP 서버

MCP 사용법

Cursor IDE 설정

Claude Desktop 설정

기타 MCP 클라이언트

MCP 리소스

MCP 도구

인증

뉴스

일정 및 캘린더

강의 및 시험

계정 및 탐색

디버깅

인증 흐름

방법 1: 대화형 브라우저 로그인 (권장)

방법 2: 수동 쿠키 설정

사용자 유형

프로젝트 구조

개발

스크립트

보안 참고 사항

라이선스

Resources

Looking for Admin?

Tools

Latest Blog Posts

MCP directory API