Nlobby MCP

🚀 N Lobby MCP Server

A Model Context Protocol (MCP) server for accessing N Lobby school portal data, providing secure access to school information via browser-based authentication.

🚀 Quick Start

This MCP server enables secure access to N Lobby school portal data. You can install it via npm or set it up for development. After installation, run the server and start accessing school information such as announcements, schedules, and learning resources.

✨ 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

2. Install dependencies:

pnpm install

3. Set up environment variables:

cp .env.example .env
# Edit .env if needed (default values should work)

4. Build the project:

pnpm run build

💻 Usage Examples

Basic Usage

Running the Server

For npm installation:

nlobby-mcp

For development installation:

pnpm run start

Advanced Usage

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

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

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

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.

📚 Documentation

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

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="your.name@nnn.ed.jp"

# 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="your.name@nnn.ac.jp"

# Use interactive login
interactive_login

# Test both calendar endpoints
test_calendar_endpoints

For Parents

# Get help for your parent account
login_help email="parent@gmail.com"

# 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"

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.