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

1. Clone the repository:

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

2. Install dependencies:

pnpm install

3. 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

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

# 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

MCP Tools

Authentication

News

Schedule & Calendar

Courses & Exams

Account & Navigation

Debugging

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

1. Log in to N Lobby in your web browser
2. Open DevTools → Application / Storage → Cookies
3. 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:

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.