neis API

mcp_server_neis_api

基于SSE的服务器，将NEIS（Nice）教育信息开放门户API公开为Model Context Protocol（MCP）服务器。

特点

• 传输方式：Server-Sent Events（SSE）
• 默认端口： 8000
• 提供工具（Tools）：

- get_school_info(school_name) ：学校基本信息（学校名称/学校代码/教育厅等） - get_school_schedule(school_code, org_code, from_date, to_date) ：学校代码+教育厅代码基础日程（学士日程） - get_school_schedule_by_name(school_name, from_date, to_date, grade=[1,2,3], target_org=None) ：直接按学校名称查询日程表（包括年级过滤器）

• 如果环境变量中没有NEIS服务密钥，则操作为降级模式：每个查询结果最多返回5个

首选参数（.env）

.env 在文件（或环境变量）中指定以下内容：

NEIS_SERVICE_KEY=당신의_서비스_키

替代变量名： SERVICE_KEY （两者中只需要一个）

如果没有密钥：

• 结果最多限制为5个。 message 在字段中 Success (degraded mode: key missing, limited to 5)显示。
• 教育局/学校日程表API调用参数中的页面大小（pSize）强制为5。

安装和运行

git clone 
cd mcp_server_neis_api
python -m venv .venv
source .venv/bin/activate  # Windows: .venv\Scripts\activate
pip install -r requirements.txt  # (requirements.txt가 있다면)
python src/server.py  # 기본 8000 포트에서 SSE 서버 시작

服务器运行时输出示例：

Start MCP server

默认端口在FastMCP内部以8000驱动（如果没有单独设置）。

使用MCP Inspector进行测试

可以使用MCP Inspector直接导航服务器。

启动命令：

npx @modelcontextprotocol/inspector python ./server.py

之后，您可以从Inspector UI连接到SSE，直接查看工具列表和调用。

客户端设置JSON示例

在MCP客户端（例如VS Code扩展或定制启动器）上使用的设置示例：

{
	"mcpServers": {
		"neis_org": {
			"type": "python",
			"command": "python",
			"args": ["./src/server.py"],
			"transport": {
				"type": "sse",
				"port": 8000
			},
			"env": {
				"NEIS_SERVICE_KEY": "${env:NEIS_SERVICE_KEY}"  
			}
		}
	}
}

port如果省略，则使用缺省值（8000）。将环境变量配置为从操作系统或启动器设置中注入。

工具详细信息

get_school_info

输入： school_name （例如： 진관초등학교) 返回： { valid, message, school_num, school_name[], school_code[], org_name[], org_code[] }

get_school_schedule

输入： school_code, org_code, from_date, to_date （YYYMMDD） 返回： { valid, message, schedule_num, event_date[], event_name[], event_type[], event_content[], valid_grade[6][] }

get_school_schedule_by_name

输入： school_name, from_date, to_date，选择 grade（默认\[1,2,3\]），选择 target_org 返回：日程表项目列表 [ { school_name, event_date, event_name, event_type, event_content, grade } ... ]

降级模式下 school_info哇 schedule 相关查询最多只返回5个结果。

日期格式

当前服务器函数为输入日期（from_date, to_date）将直接传递给NEIS API，因此建议使用YYYYMMDD格式。

错误处理

• NEIS API错误 valid=False一起 message 向字段返回原因消息
• 解析错误 Error parsing ... 消息

开发技巧

• .env 更改后重新启动服务器才能反映新密钥。
• 未来扩展：可应用高速缓存、计划重复数据删除、超时/刷新逻辑

许可证

有关本项目的许可，请参阅存储库中的LICENSE文件。