nlobby-cli

v1.4.5

Published

19 days ago

CLI and MCP server for N Lobby school portal

0High
0Medium
0Low

minagishl

cli mcp mcp-server nlobby school portal

N Lobby CLI

Note: The developer assumes no responsibility for any damages that may occur from using this tool. This software was developed for educational purposes and its operation is not guaranteed.

A dual-mode CLI and Model Context Protocol (MCP) server for accessing N Lobby school portal data. Use it interactively from the terminal with nlobby, or connect it to an AI assistant as an MCP server with nlobby serve.

Features

CLI Mode: Access N Lobby data directly from the terminal — news, schedule, courses, profile, and more
MCP Mode: Full MCP server compatible with Claude, Cursor, and other MCP-enabled AI assistants
Browser-based Authentication: Interactive login via automated Puppeteer browser window
Session Persistence: CLI mode saves cookies to ~/.nlobby/session for seamless subsequent use
School Information Access: Retrieve announcements, schedules, and learning resources
Required Courses Management: Access required course information and academic data
Multiple Calendar Types: Support for both personal and school calendars
User Role Support: Different access levels for students, parents, and staff

Installation

Option 1: Install from npm (Recommended)

npm install -g nlobby-cli

Option 2: Development Installation

Clone the repository:

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

Install dependencies:

pnpm install

Build the project:

pnpm run build

Configuration

Create a .env file if you need to override defaults (optional):

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

CLI Usage

Authentication

# 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

News

# 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

# Mark as read
nlobby news read 980

Schedule & Calendar

# 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

Courses

# All required courses
nlobby courses

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

Profile & Health

nlobby profile
nlobby health

MCP Server

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

All commands support --json to output raw JSON instead of formatted text.

MCP Usage

Cursor IDE Setup

Add the following to your Cursor settings (~/.cursor/config.json):

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

Claude Desktop Setup

Add to your Claude Desktop config (~/Library/Application Support/Claude/claude_desktop_config.json on macOS):

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

Other MCP Clients

For any MCP-compatible client, use:

Command: nlobby serve (if installed globally) or node /path/to/dist/index.js serve
Protocol: stdio
Environment: Optional environment variables as listed in the Configuration section

MCP Resources

| URI | Description | | --------------------------- | ----------------------------------------- | | nlobby://news | School news and notices | | nlobby://schedule | Daily class schedule and events | | nlobby://required-courses | Required courses and academic information | | nlobby://user-profile | Current user information |

MCP Tools

Authentication

| Tool | Description | | ----------------------- | ----------------------------------------------- | | interactive_login | Open browser for manual login (recommended) | | login_help | Personalized login help and troubleshooting | | set_cookies | Manually set authentication cookies | | check_cookies | Check authentication cookie status | | verify_authentication | Verify authentication status across all clients |

News

| Tool | Key Parameters | Description | | ---------------------- | ---------------------------- | ------------------------------------- | | get_news | category? limit? sort? | Retrieve school news with filtering | | get_news_detail | newsId markAsRead? | Full detail for a specific article | | mark_news_as_read | ids (array) | Mark articles as read | | get_unread_news_info | | Unread count and important-news flags |

Schedule & Calendar

| Tool | Key Parameters | Description | | ------------------------- | -------------------------------------------------- | --------------------------------- | | get_schedule | date? | Schedule for a date (YYYY-MM-DD) | | get_calendar_events | calendar_type? from_date? to_date? period? | Calendar events (personal/school) | | test_calendar_endpoints | from_date? to_date? | Test both calendar endpoints | | get_calendar_filters | | Lobby calendar filter definitions |

Courses & Exams

| Tool | Key Parameters | Description | | ---------------------- | -------------------------------- | --------------------------------------- | | get_required_courses | grade? semester? category? | Required courses with progress tracking | | check_exam_day | date? | Check if a date is an exam day | | finish_exam_day_mode | | End exam day mode | | get_exam_otp | | Get one-time password for exam |

Account & Navigation

| Tool | Description | | ----------------------------- | -------------------------------------------- | | get_account_info | Extract account info from Next.js page | | get_student_card_screenshot | Capture student ID card screenshot | | update_last_access | Update last access timestamp | | get_navigation_menus | Main navigation menu list | | get_notifications | Notification messages | | get_user_interests | User interest tags (with optional icon data) | | get_interest_weights | Interest weight scale definitions |

Debugging

| Tool | Key Parameters | Description | | -------------------- | --------------------- | ------------------------------ | | health_check | | Test N Lobby API connection | | debug_connection | endpoint? | Detailed connection debugging | | test_page_content | endpoint? length? | Page content retrieval testing | | test_trpc_endpoint | method params? | Test a specific tRPC endpoint |

Authentication Flow

Method 1: Interactive Browser Login (Recommended)

CLI:

nlobby login

MCP tool: interactive_login

A browser window opens automatically. Complete the N Lobby login, and cookies are extracted and saved.

Method 2: Manual Cookie Setup

Log in to N Lobby in your web browser
Open DevTools → Application / Storage → Cookies
Copy all cookies as a string

CLI:

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

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

User Types

The server supports three user types based on email domain:

| Type | Email Domain | | ------------ | -------------------------- | | Students | @nnn.ed.jp | | Staff | @nnn.ac.jp | | Parents | Any other registered email |

Project Structure

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)

Development

Scripts

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

Security Notes

CLI cookies are stored in ~/.nlobby/session (plain text — protect accordingly)
MCP mode keeps all authentication tokens in memory only
Browser automation is used only for authentication, not data scraping
No sensitive data is logged

License

This project is licensed under the MIT License — see the LICENSE file for details.

Published

Vulnerabilities

Links

Maintainers

Keywords

Readme

N Lobby CLI

Features

Installation

Option 1: Install from npm (Recommended)

Option 2: Development Installation

Configuration

CLI Usage

Authentication

News

Schedule & Calendar

Courses

Profile & Health

MCP Server

MCP Usage

Cursor IDE Setup

Claude Desktop Setup

Other MCP Clients

MCP Resources

MCP Tools

Authentication

News

Schedule & Calendar

Courses & Exams

Account & Navigation

Debugging

Authentication Flow

Method 1: Interactive Browser Login (Recommended)

Method 2: Manual Cookie Setup

User Types

Project Structure

Development

Scripts

Security Notes

License