Korea Welfare MCP Server

Model Context Protocol (MCP) server providing access to Korean government welfare benefits and support programs.

한국어 문서 (Korean)

Features

This MCP server enables AI assistants to answer questions about Korean welfare benefits and government support programs:

• 🔍 Search Benefits: Find welfare services by keywords
• ✅ Check Eligibility: Match benefits to user's age, income, region
• 📄 Get Details: Retrieve detailed information about specific benefits
• 🎯 Lifecycle Search: Find benefits by life stage (birth, education, employment, etc.)
• 👥 Youth Policies: Search policies specifically for young adults (YouthCenter)

APIs Used

| API | Status | Purpose | Provider | |-----|--------|---------|----------| | 복지로 (Bokjiro) | ✅ Active | Welfare benefit information | Korea Social Security Information Service | | 온통청년 (Youth Center) | ✅ Active | Youth-focused policies | Korea Employment Information Service | | 정부24 (GOV24) | 📋 Planned | Government services | Ministry of the Interior and Safety |

All APIs are free and publicly available from Korean government open data portals.

Installation

Prerequisites

• Node.js 22 or higher
• API keys from Korean government portals (see below)

Get API Keys

1. Public Data Portal API Key (공공데이터포털)

This single key is used for multiple government APIs (Bokjiro, GOV24, etc.):

1. Visit 공공데이터포털
2. Sign up and log in
3. Search for "한국사회보장정보원 중앙부처복지서비스" (Bokjiro)
4. Click "활용신청" (Request Access)
5. Your API key will be issued immediately
6. Important: Use the decoded (원본) key value, not the encoded version

You can use this same key for other Public Data Portal APIs.

2. Youth Center API Key (온통청년) - Optional

Required for youth policy features (currently pending API approval):

1. Visit 온통청년
2. Sign up and log in
3. Go to OPEN API menu
4. Request API authentication key
5. Apply for "청년정책 API" access
6. Wait for approval (may take several days)

Install Server

Option 1: Install from npm (Recommended)

npm install -g korea-welfare-mcp-server

Option 2: Build from Source

# Clone the repository
git clone https://github.com/SimDaSong/korea-welfare-mcp-server.git
cd korea-welfare-mcp-server

# Install dependencies
npm install

# Build
npm run build

Configuration

Environment Variables

First, obtain your API keys from the Get API Keys section and prepare these environment variables:

| Variable | Description | |---|---| | PUBLIC_DATA_API_KEY | Public Data Portal API key (for Bokjiro, etc.) | | YOUTHCENTER_API_KEY | Youth Center API key (separate key) |

MCP Client Setup

This MCP server works with any client that supports the Model Context Protocol.

General MCP configuration format:

If installed via npm (recommended):

{
  "mcpServers": {
    "korea-welfare": {
      "command": "npx",
      "args": ["-y", "korea-welfare-mcp-server"],
      "env": {
        "PUBLIC_DATA_API_KEY": "your_decoded_public_data_api_key_here",
        "YOUTHCENTER_API_KEY": "your_youthcenter_api_key_here"
      }
    }
  }
}

If built from source:

{
  "mcpServers": {
    "korea-welfare": {
      "command": "node",
      "args": ["/absolute/path/to/korea-welfare-mcp-server/dist/index.js"],
      "env": {
        "PUBLIC_DATA_API_KEY": "your_decoded_public_data_api_key_here",
        "YOUTHCENTER_API_KEY": "your_youthcenter_api_key_here"
      }
    }
  }
}

Note: YOUTHCENTER_API_KEY is optional and only required for youth policy features.

Available Tools

1. welfare_search_benefits

Search for welfare benefits by keyword.

Parameters:

• query (string, required): Search keyword (e.g., "청년", "주거", "출산")
• limit (number, default=20): Number of results (1-100)
• offset (number, default=0): Pagination offset
• response_format ("markdown" | "json", default="markdown"): Output format

Example:

"Find welfare benefits for youth housing support"

2. welfare_check_eligibility

Find benefits matching user's eligibility criteria.

Parameters:

• age (number, optional): Age
• income_percentile (number, optional): Income as % of median (e.g., 180)
• region (string, optional): Region (e.g., "서울", "경기")
• employment_status ("employed" | "unemployed" | "student", optional): Employment status
• life_event (string, optional): Life event (e.g., "결혼", "출산")
• limit (number, default=10): Number of results
• response_format ("markdown" | "json"): Output format

Example:

"I'm 29, living in Seoul, earning 150% of median income. What benefits can I get?"

3. welfare_get_detail

Get detailed information about a specific benefit.

Parameters:

• benefit_id (string, required): Benefit service ID
• response_format ("markdown" | "json"): Output format

Example:

"Show me details for benefit WLF00003180"

4. welfare_search_by_lifecycle

Search benefits by life stage.

Parameters:

• lifecycle (enum, required): One of:
  • birth: Birth and newborn support
  • child_care: Childcare and parenting
  • education: Education and scholarships
  • employment: Employment and job training
  • marriage: Marriage and newlyweds
  • housing: Housing and rent support
  • retirement: Retirement and elderly care
  • etc: Other
• limit (number, default=20): Number of results
• response_format ("markdown" | "json"): Output format

Example:

"What benefits are available for new parents?"

5. welfare_search_youth_policies

Search policies specifically for youth (ages 15-34).

Parameters:

• keyword (string, optional): Policy keyword
• region (string, optional): Region filter
• category (enum, optional): One of:
  • employment: Employment and startup
  • education: Education
  • welfare: Welfare
  • housing: Housing
  • culture: Culture and leisure
• limit (number, default=20): Number of results
• response_format ("markdown" | "json"): Output format

Example:

"Find employment support programs for young adults"

Development

# Install dependencies
npm install

# Build
npm run build

# Watch mode (auto-rebuild on changes)
npm run watch

# Run server
npm start

Testing

# Run unit tests
npm test

# Run tests in watch mode
npm run test:watch

# Run tests with coverage
npm run test:coverage

# Run integration tests (requires API key)
npm run test:integration

Test Structure:

__tests__/
├── services/                 # Service unit tests
│   ├── bokjiro.test.ts
│   └── youthcenter.test.ts
├── tools/                    # Tool handler tests
│   ├── search.test.ts
│   ├── detail.test.ts
│   ├── eligibility.test.ts
│   ├── lifecycle.test.ts
│   └── youth.test.ts
├── utils/                    # Utility tests
│   ├── api.test.ts
│   ├── errors.test.ts
│   ├── eligibility.test.ts
│   └── format.test.ts
└── integration/              # Integration tests (requires API keys)
    ├── bokjiro.test.ts
    └── youthcenter.test.ts

Implementation Status

✅ Fully Implemented

• 복지로 (Bokjiro) API: All features working and tested
  • Search benefits (welfare_search_benefits)
  • Check eligibility (welfare_check_eligibility)
  • Get benefit details (welfare_get_detail)
  • Search by lifecycle (welfare_search_by_lifecycle)
• 온통청년 (Youth Center) API: All features working and tested
  • Search youth policies (welfare_search_youth_policies)

📋 Planned

• 정부24 (GOV24) API: Not yet implemented
• See GitHub Issues for roadmap

Architecture

korea-welfare-mcp-server/
├── src/
│   ├── index.ts              # MCP server initialization
│   ├── types.ts              # TypeScript interfaces
│   ├── constants.ts          # API URLs, constants
│   ├── services/             # API clients
│   │   ├── bokjiro.ts        # 복지로 API
│   │   ├── gov24.ts          # (future) GOV24 API
│   │   └── youthcenter.ts    # 온통청년 API
│   ├── tools/                # MCP tool implementations
│   │   ├── search.ts
│   │   ├── eligibility.ts
│   │   ├── detail.ts
│   │   ├── lifecycle.ts
│   │   └── youth.ts
│   ├── schemas/              # Zod input validation
│   │   └── inputs.ts
│   └── utils/                # Utilities
│       ├── api.ts            # HTTP request helper
│       ├── errors.ts         # Error handling
│       ├── eligibility.ts    # Eligibility parsing
│       └── format.ts         # Response formatting
└── dist/                     # Compiled JavaScript

Contributing

Contributions are welcome!

License

MIT

Disclaimer

This is an unofficial project. All data comes from public Korean government APIs. Always verify benefit information with official sources before applying.