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

<details> <summary>Setup with Cursor and Other MCP Clients</summary>

Cursor IDE Setup

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

</details>

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 per…