Skip to main content
Glama

N Lobby MCP Server

by minagishl
npmGitHub
TypeScript
MIT License
9
3
  • Apple
OverviewInspectNewEndpointsSchemaRelated ServersReviewsScore
Need Help?View Source CodeReport Issue

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

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 news articles as read (supports multiple IDs)

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="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 (single ID) mark_news_as_read ids=["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"

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.

Deploy Server
A
security – no known vulnerabilities
A
license - permissive license
A
quality - confirmed to work

How are these scores calculated?

local-only server

The server can only run on the client's local machine because it depends on local resources.

Tools

View all tools

A Model Context Protocol server that provides secure access to N Lobby school portal data including announcements, schedules, and learning resources through browser-based authentication.

  1. Features
    1. Installation
      1. Option 1: Install from npm (Recommended)
      2. Option 2: Development Installation
    2. Configuration
      1. Usage
        1. Running the Server
        2. Cursor IDE Setup
        3. Claude Desktop Setup
        4. Other MCP Clients
        5. MCP Resources
        6. MCP Tools
        7. MCP Prompts
      2. Authentication Flow
        1. Method 1: Interactive Browser Login (Recommended)
        2. Method 2: Manual Cookie Setup
      3. Quick Start Examples
        1. For Students
        2. For Staff
        3. For Parents
        4. Troubleshooting
        5. Required Courses
        6. Calendar Events
        7. Cookie Format
      4. User Types
        1. Development
          1. Scripts
          2. Project Structure
          3. Architecture
        2. Security Notes
          1. Troubleshooting
            1. Common Issues
            2. Debug Tools
          2. License

            Related MCP Servers

            • LeetCode MCP Server

              jinzcdev
              A
              security
              A
              license
              A
              quality
              A Model Context Protocol server that provides integration with LeetCode APIs, enabling automated interaction with programming problems, contests, solutions, and user data across both leetcode.com and leetcode.cn platforms.
              Last updated -
              9
              100
              54
              MIT License

            • MCP Server Sample

              antonioscapellato
              -
              security
              A
              license
              -
              quality
              An educational implementation of a Model Context Protocol server that demonstrates how to build a functional MCP server integrating with various LLM clients.
              Last updated -
              2
              MIT License

            • OpenEdu MCP Server

              Cicatriiz
              -
              security
              A
              license
              -
              quality
              A comprehensive Model Context Protocol server providing educational resources and curriculum planning support with intelligent filtering across multiple educational APIs.
              Last updated -
              1
              MIT License

            • NetBox Read/Write MCP Server

              Deployment-Team
              -
              security
              A
              license
              -
              quality
              A Model Context Protocol server that provides safe, intelligent read/write access to NetBox instances, designed with safety-first principles for Large Language Model automation.
              Last updated -
              MIT License

            View all related MCP servers

            New MCP Servers

            MCP directory API

            We provide all the information about MCP servers via our MCP API.

            curl -X GET 'https://glama.ai/api/mcp/v1/servers/minagishl/nlobby-mcp'

            If you have feedback or need assistance with the MCP directory API, please join our Discord server