Submit
minagishl

N Lobby MCP Server

Community minagishl
Updated

MCP server for N Lobby school portal

N Lobby MCP Server

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

A Model Context Protocol (MCP) server for accessing N Lobby school portal data. This server provides secure access to school information including announcements, schedules, and learning resources through browser-based authentication.

Features

  • Browser-based Authentication: Interactive login via automated browser window
  • Cookie-based Session Management: Secure session handling with NextAuth.js cookies
  • 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
  • MCP Protocol Compliance: Full compatibility with MCP-enabled AI assistants
  • Advanced Testing Tools: Built-in debugging and testing capabilities

Installation

Option 1: Install from npm (Recommended)

npm install -g nlobby-mcp

Option 2: Development Installation

  1. Clone the repository:
git clone https://github.com/minagishl/nlobby-mcp.git
cd nlobby-mcp
  1. Install dependencies:
pnpm install
  1. Set up environment variables:
cp .env.example .env
# Edit .env if needed (default values should work)
  1. Build the project:
pnpm run build

Configuration

Create a .env file with the following variables (optional, defaults provided):

# N Lobby Configuration
NLOBBY_BASE_URL=https://nlobby.nnn.ed.jp

# MCP Server Configuration
MCP_SERVER_NAME=nlobby-mcp
MCP_SERVER_VERSION=1.0.0

Usage

Running the Server

For npm installation:

nlobby-mcp

For development installation:

pnpm run start
Setup with Cursor and Other MCP Clients

Cursor IDE Setup

Install MCP Server

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

{
  "mcpServers": {
    "nlobby": {
      "command": "npx",
      "args": ["-y", "nlobby-mcp"],
      "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-mcp"],
      "env": {
        "NLOBBY_BASE_URL": "https://nlobby.nnn.ed.jp"
      }
    }
  }
}

Other MCP Clients

For any MCP-compatible client, use:

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

MCP Resources

The server provides the following resources:

  • 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

Available tools:

Authentication Tools
  • interactive_login - Open browser for manual login to N Lobby (recommended)
  • login_help - Get 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
Data Retrieval Tools
  • get_news - Retrieve school news with filtering and sorting options
  • get_news_detail - Retrieve detailed information for a specific news article
  • get_required_courses - Retrieve required courses information with filtering options
  • get_schedule - Get schedule for a specific date (backward compatibility)
  • get_calendar_events - Get calendar events with advanced options (personal/school)
  • test_calendar_endpoints - Test both personal and school calendar endpoints
  • mark_news_as_read - Mark a news article as read
Debugging Tools
  • health_check - Test N Lobby API connection
  • debug_connection - Debug N Lobby connection with detailed information
  • test_page_content - Test page content retrieval and show sample content
  • test_trpc_endpoint - Test specific tRPC endpoint with detailed response

MCP Prompts

This server does not provide any pre-configured prompts.

Authentication Flow

Method 1: Interactive Browser Login (Recommended)

  1. Use the interactive_login tool (no credentials required)
  2. A browser window will open to N Lobby
  3. Complete the login process manually in the browser
  4. The system will detect when you're logged in and extract cookies automatically
  5. Access real N Lobby data immediately

Method 2: Manual Cookie Setup

  1. Login to N Lobby via web browser
  2. Extract cookies from browser developer tools:
    • Open Developer Tools (F12)
    • Go to Application/Storage tab
    • Copy all cookies as a string
  3. Use set_cookies tool with the complete cookie string
  4. Use health_check tool to verify connection
  5. Access real N Lobby data via other tools

Quick Start Examples

For Students

# Get help for your student account
login_help email="[email protected]"

# Use interactive login (recommended)
interactive_login

# Get today's news
get_news

# Get detailed information for a specific news article
get_news_detail newsId="980"

# Get news detail and mark as read
get_news_detail newsId="980" markAsRead=true

# Get personal calendar events for today
get_calendar_events calendar_type="personal" period="today"

# Get school calendar events for this week
get_calendar_events calendar_type="school" period="week"

# Get required courses information
get_required_courses

# Get required courses for a specific grade
get_required_courses grade=2

# Mark a news article as read
mark_news_as_read id="980"

For Staff

# Get help for your staff account
login_help email="[email protected]"

# Use interactive login
interactive_login

# Test both calendar endpoints
test_calendar_endpoints

For Parents

# Get help for your parent account
login_help email="[email protected]"

# Use interactive login
interactive_login

# Check your child's news
get_news

# Get your child's schedule
get_calendar_events calendar_type="personal" period="today"

Troubleshooting

# Get general help
login_help

# Check connection status
health_check

# Check cookie status
check_cookies

# Verify authentication across all systems
verify_authentication

# Debug connection with detailed info
debug_connection

# Test page content retrieval
test_page_content endpoint="/news"

Required Courses

The get_required_courses tool allows you to retrieve academic course information:

# Get all required courses
get_required_courses

# Filter by grade level
get_required_courses grade=1
get_required_courses grade=2

# Combine multiple filters
get_required_courses grade=2 semester="2024"

The response includes comprehensive course information:

  • Course Details: Subject code/name, curriculum code/name
  • Academic Credits: Academic credit hours and approved credits
  • Progress Tracking: Report completion percentage, average scores
  • Status Information: Acquisition status, evaluation grades
  • Test Information: Exam status, periodic exam results, makeup exam URLs
  • Schooling Data: Attendance counts and requirements
  • Time Information: Term year, grade level (1年次, 2年次, 3年次)
  • Computed Fields: Progress percentage, completion status, average scores

Calendar Events

The get_calendar_events tool supports advanced options:

# Get personal calendar for today
get_calendar_events calendar_type="personal" period="today"

# Get school calendar for this week
get_calendar_events calendar_type="school" period="week"

# Get events for a specific date range
get_calendar_events calendar_type="personal" from_date="2024-01-15" to_date="2024-01-20"

# Get events for a single day
get_calendar_events calendar_type="personal" from_date="2024-01-15"

Cookie Format

When using set_cookies, provide the complete cookie string from browser:

__Secure-next-auth.session-token=ey...; __Host-next-auth.csrf-token=abc123...; other-cookies=values;

User Types

The server supports three user types based on email domain:

  • Students: @nnn.ed.jp
  • Staff: @nnn.ac.jp
  • Parents: Any other registered email addresses (Gmail, Yahoo, company emails, etc.)

Development

Scripts

  • pnpm run build - Build the TypeScript project
  • pnpm run dev - Watch mode for development
  • pnpm run start - Start the MCP server
  • pnpm run test - Run tests
  • pnpm run lint - Lint the code
  • pnpm run format - Format the code

Project Structure

src/
├── index.ts              # Entry point
├── server.ts             # MCP server implementation
├── api.ts                # N Lobby API integration
├── browser-auth.ts       # Browser automation for login
├── credential-manager.ts # User credential validation and management
├── nextauth.ts           # NextAuth.js session handling
├── trpc-client.ts        # tRPC client for API calls
├── config.ts             # Configuration management
├── logger.ts             # Logging utilities
└── types.ts              # TypeScript type definitions

Architecture

The server uses multiple layers for authentication and API access:

  1. Browser Authentication: Automated browser for interactive login
  2. Cookie Management: Handles NextAuth.js session cookies
  3. HTTP Client: Axios-based client for REST API calls
  4. tRPC Client: Type-safe client for tRPC endpoints
  5. Credential Manager: Validates user types and provides guidance

Security Notes

  • All authentication tokens are stored in memory only
  • The server uses secure cookie-based authentication
  • Access is restricted to authorized N High School Group email domains
  • No sensitive data is logged or persisted
  • Browser automation is used only for authentication, not data scraping

Troubleshooting

Common Issues

  1. Authentication Failed: Use interactive_login for the most reliable authentication
  2. Cookie Sync Issues: Run verify_authentication to check synchronization
  3. Connection Problems: Use health_check and debug_connection for diagnosis
  4. Empty Results: Ensure you're authenticated and have proper permissions

Debug Tools

The server includes comprehensive debugging tools:

  • debug_connection - Network and authentication debugging
  • test_page_content - Content retrieval testing
  • test_trpc_endpoint - API endpoint testing
  • verify_authentication - Authentication status verification

License

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

MCP Server · Populars

MCP Server · New