N Lobby

You can run a local MCP server that securely accesses N Lobby school portal data and exposes it to MCP clients. This server handles browser-based authentication, cookie-based sessions, and a range of school information endpoints so you can query news, schedules, calendars, and more from your AI assistants or automation tools.

How to use

Install and run the MCP server, then connect your MCP client to access school data. You can start the server in development mode for testing or install a global binary for easier long-term use. Use the standard commands to start and then use supported tools to fetch news, schedules, and calendar events. Authentication can be performed interactively in a browser or you can set authentication cookies manually if needed.

How to install

Prerequisites: Node.js and a package manager (npm or pnpm) installed on your system.

# Option 1: Install the MCP server globally (recommended for quick usage)
npm install -g nlobby-mcp

# Option 2: Development installation (clone repo and build locally)
# 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 (defaults work)
cp .env.example .env
# Edit .env if needed

# 4) Build the project
pnpm run build

Configuration and startup

Configure the server by setting environment variables. The following values are used to identify the MCP server and base URL for N Lobby access.

# 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

Starting the MCP server

You can start the server in two ways. Choose the one that matches how you installed it.

# If you installed the server globally
nlobby-mcp

# If you installed for development
pnpm run start

Additional setup when using MCP clients

If you use MCP clients, ensure they can reach the server endpoint and have the required environment variables set. The server uses a browser-based authentication flow and session cookies managed through NextAuth.js.

Security notes and best practices

All authentication tokens are stored in memory and cookies are secured. Access is restricted to authorized N Lobby-related email domains. Do not log or persist sensitive data, and use browser-based authentication only for initial login.

Troubleshooting

If authentication or connectivity issues occur, use the built-in tools to diagnose and fix problems.

# Common checks
health_check
check_cookies
verify_authentication

# Debug and tests
debug_connection
test_page_content endpoint="/news"

Notes on usage with MCP clients

After starting, you can use tools to fetch school news, schedules, calendars, and course information. Use the interactive login flow when possible for the most reliable authentication, or manually set cookies if needed.

Available tools

interactive_login

Open a browser window to login to N Lobby interactively using your MCP client. This is the recommended login flow.

login_help

Provide personalized guidance and troubleshooting steps for authentication issues.

set_cookies

Manually set the authentication cookies from a browser session.

check_cookies

Verify the current authentication cookies are valid.

verify_authentication

Check authentication status across all connected MCP clients.

get_news

Retrieve school news with optional filtering and sorting.

get_news_detail

Fetch detailed information for a specific news item.

get_required_courses

Retrieve required courses information with optional filters.

get_schedule

Get a schedule for a given date (backward compatible).

get_calendar_events

Fetch calendar events with support for personal and school calendars.

test_calendar_endpoints

Test both personal and school calendar endpoints.

mark_news_as_read

Mark one or more news articles as read.

health_check

Test the N Lobby API connection.

debug_connection

Run a detailed network and authentication debug to diagnose issues.

test_page_content

Test page content retrieval from endpoints like /news.

test_trpc_endpoint

Test a specific tRPC endpoint with a detailed response.