README.md•2.8 kB
# NEIS MCP Server
MCP (Model Context Protocol) server for Korean NEIS (National Education Information System).
## Features
Provides 4 MCP tools to access Korean school information:
### 1. `neis.school.search`
Search for schools by name.
**Input:**
- `name` (string): School name to search for
**Output:**
- `schoolCode`: School identifier
- `officeCode`: Education office code
- `schoolName`: Full school name
- `address`: School address
- `type`: School type
### 2. `neis.meal`
Get school meal information.
**Input:**
- `schoolCode` (string): School code from search
- `officeCode` (string): Office code from search
- `ymd` (string, optional): Date in YYYYMMDD format (defaults to today)
**Output:**
- `date`: Query date
- `meals`: Array of meal information (breakfast, lunch, dinner)
### 3. `neis.timetable`
Get class timetable.
**Input:**
- `schoolCode` (string): School code from search
- `grade` (string, optional): Grade level
- `className` (string, optional): Class name/number
- `ymd` (string, optional): Date in YYYYMMDD format (defaults to today)
**Output:**
- `date`: Query date
- `timetable`: Array of class periods with subjects and teachers
### 4. `neis.schedule`
Get school events and schedules.
**Input:**
- `schoolCode` (string): School code from search
- `officeCode` (string, optional): Office code from search
- `ymd` (string, optional): Date in YYYYMMDD format (defaults to today)
**Output:**
- `date`: Query date
- `events`: Array of school events
## Setup
### Environment Variables
Create a `.env.local` file:
```env
NEIS_API_KEY=your_neis_api_key_here
```
Get your NEIS API key from: https://open.neis.go.kr/
### Installation
```bash
npm install
```
### Development
```bash
npm run dev
```
### Deploy to Vercel
1. Push this repository to GitHub
2. Import to Vercel
3. Add `NEIS_API_KEY` environment variable
4. Deploy
## Usage with MCP Clients
Connect to this server using the deployed Vercel URL:
**SSE Transport:**
```
https://your-deployment.vercel.app/api/sse
```
**HTTP Transport:**
```
https://your-deployment.vercel.app/api/http
```
## Example Workflow
1. Search for a school:
```
neis.school.search({ name: "서울고등학교" })
```
2. Use the returned codes to get meal info:
```
neis.meal({
schoolCode: "B100000658",
officeCode: "B10",
ymd: "20240115"
})
```
3. Get timetable:
```
neis.timetable({
schoolCode: "B100000658",
grade: "1",
className: "1"
})
```
4. Check school events:
```
neis.schedule({
schoolCode: "B100000658",
officeCode: "B10"
})
```
## Tech Stack
- Next.js 15 (App Router)
- TypeScript
- mcp-handler ^1.0.3
- @modelcontextprotocol/sdk
- zod (schema validation)
- axios (HTTP client)
- Vercel (deployment)
## License
MIT