Nlobby MCP

N大堂CLI

注： 开发人员对使用此工具可能造成的任何损坏不承担任何责任。此软件是为教育目的而开发的，其操作不受保证。

用于访问N Lobby学校门户数据的双模CLI和模型上下文协议（MCP）服务器。从终端以交互方式使用它 nlobby，或将其作为MCP服务器连接到AI助手 nlobby serve.

特性

• 命令行接口命令模式：直接从终端访问N Lobby数据——新闻、日程、课程、个人资料等
• MCP模式：与Claude、Cursor和其他启用MCP的AI助手兼容的完整MCP服务器
• 基于浏览器的身份验证：通过自动Puppeteer浏览器窗口进行交互式登录
• 会话保持：CLI模式将Cookie保存到 ~/.nlobby/session 用于无缝后续使用
• 学校信息访问：检索公告、时间表和学习资源
• 必修课程管理：访问所需的课程信息和学术数据
• 多种日历类型：支持个人日历和学校日历
• 用户角色支持：学生、家长和教职员工的不同访问级别

安装

选项1：从npm安装（推荐）

npm install -g nlobby-cli

选项2：开发安装

1. 克隆存储库：

git clone https://github.com/minagishl/nlobby-cli.git
cd nlobby-cli

1. 安装依赖项：

pnpm install

1. 构建项目：

pnpm run build

配置

创建一个 .env 如果需要覆盖默认值，请使用文件（可选）：

NLOBBY_BASE_URL=https://nlobby.nnn.ed.jp
MCP_SERVER_NAME=nlobby-cli
MCP_SERVER_VERSION=1.0.0

______________________________________________________________________

命令行用法

认证

# Interactive browser login (recommended)
nlobby login

# Set cookies manually
nlobby cookies set "__Secure-next-auth.session-token=ey...;"

# Check current authentication status
nlobby cookies check

新闻

# List latest news (default: 10, newest first)
nlobby news

# Filter and sort
nlobby news --limit 20 --category お知らせ --sort oldest --unread

# Show full article
nlobby news show 980

# Download the first attachment to /tmp
nlobby news download 980 --index 1 --output-dir /tmp

# Mark as read
nlobby news read 980

日程表和日历

# Today's schedule
nlobby schedule

# Specific date
nlobby schedule 2026-04-01

# This week's personal calendar
nlobby calendar

# School calendar for a date range
nlobby calendar --type school --from 2026-04-01 --to 2026-04-07

课程

# All required courses
nlobby courses

# Filter by grade / semester
nlobby courses --grade 2 --semester 2025

个人资料和健康状况

nlobby profile
nlobby health

MCP服务器

# Start MCP server (stdio transport)
nlobby serve
# or
nlobby mcp

所有命令支持 --json 输出原始JSON而不是格式化文本。

______________________________________________________________________

MCP使用

Setup with Cursor and Other MCP Clients

光标IDE设置


将以下内容添加到光标设置中(~/.cursor/config.json):

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

Claude桌面设置

添加到您的Claude桌面配置(~/Library/Application Support/Claude/claude_desktop_config.json 在macOS上）：

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

其他MCP客户端

对于任何兼容MCP的客户端，请使用：

• 命令: nlobby serve （如果全局安装）或 node /path/to/dist/index.js serve
• 协议标准： stdio
• 环境：配置部分中列出的可选环境变量

MCP资源

MCP工具

认证

新闻

日程表和日历

课程与考试

帐户和导航

调试

______________________________________________________________________

身份验证流程

方法1：交互式浏览器登录（推荐）

CLI：

nlobby login

MCP工具： interactive_login

浏览器窗口会自动打开。完成N Lobby登录，Cookie将被提取并保存。

方法2：手动设置Cookie

1. 在您的网络浏览器中登录N Lobby
2. 打开DevTools→ 应用/存储→ Cookie
3. 将所有Cookie复制为字符串

CLI：

nlobby cookies set "__Secure-next-auth.session-token=ey...;"

MCP工具： set_cookies cookies="__Secure-next-auth.session-token=ey...;"

______________________________________________________________________

用户类型

服务器支持基于电子邮件域的三种用户类型：

______________________________________________________________________

项目结构

src/
├── index.ts              # Entry point — CLI vs MCP mode detection
├── config.ts             # Configuration management
├── logger.ts             # Logging utilities
├── trpc-client.ts        # tRPC client for API calls
├── types.ts              # TypeScript type definitions
├── api/
│   ├── index.ts          # NLobbyApi facade + session persistence
│   ├── context.ts        # ApiContext interface
│   ├── shared.ts         # Shared utilities (fetchRenderedHtml, …)
│   ├── news.ts           # News functions
│   ├── schedule.ts       # Schedule / calendar functions
│   ├── courses.ts        # Course / exam functions
│   ├── account.ts        # Account info / student card functions
│   ├── navigation.ts     # Navigation / notification / interest functions
│   └── health.ts         # Health check / debug functions
├── auth/
│   ├── browser.ts        # Puppeteer browser authentication
│   ├── nextauth.ts       # NextAuth.js session handling
│   └── credentials.ts    # Credential validation and guidance
├── cli/
│   ├── index.ts          # Commander program wiring
│   ├── commands/         # login, news, schedule, courses, profile, health, serve
│   └── formatters/       # Human-readable output formatters
└── mcp/
    └── server.ts         # MCP server (28 tools, 4 resources)

______________________________________________________________________

发展

脚本

pnpm run build   # Build (esbuild bundle + tsc type declarations)
pnpm run dev     # Watch mode
pnpm run start   # Start MCP server
pnpm run lint    # Lint
pnpm run format  # Format

安全说明

• CLI Cookie存储在 ~/.nlobby/session （纯文本——相应保护）
• MCP模式仅将所有身份验证令牌保存在内存中
• 浏览器自动化仅用于身份验证，不用于数据抓取
• 未记录敏感数据

______________________________________________________________________

许可证

该项目根据MIT许可证获得许可——请参阅 许可证 文件以获取详细信息。