Content
# KOSIS MCP Server
KOSIS(Korea Open Statistical Information Service) OpenAPI provided as a [Model Context Protocol](https://modelcontextprotocol.io) tool.
## Tool List
| Tool | Description | Main Use |
|------|------|----------|
| `kosis_search` | Integrated search — Find statistical tables by keyword | First step to find orgId and tblId |
| `kosis_get_data` | Retrieve statistical data — Actual data retrieval | Essential tool. Secure numerical data |
| `kosis_region_code` | Automatic region code mapping — Find codes by natural language | **Required before kosis_get_data** |
| `kosis_list` | Statistical list — Explore lists by topic or organization | Discover available statistics |
| `kosis_meta` | Statistical metadata — Purpose, legal basis, etc. | Confirm statistical metadata |
| `kosis_table_info` | Table description — Classification items, units, sources, etc. | Understand data structure |
| `kosis_indicator` | Key indicators — Core economic and social indicators | Retrieve key national indicators |
## Installation
```bash
git clone https://github.com/simonsez9510/kosis-mcp.git
cd kosis-mcp
npm install
npm run build
```
## API Key Issuance
1. Visit [KOSIS Sharing Service](https://kosis.kr/openapi/)
2. Register and log in
3. **Application for Use** → Apply for Open API service (automatic approval)
4. Check authentication key in **My Page**
## Claude Code Configuration
Add to `.claude/.mcp.json`:
```json
{
"mcpServers": {
"kosis": {
"command": "node",
"args": ["/path/to/kosis-mcp/build/index.js"],
"env": {
"KOSIS_API_KEY": "issued_authentication_key"
}
}
}
}
```
## Usage Guide
### Basic Workflow
Typically involves **2 steps** to retrieve KOSIS data:
```
1. Search for statistical tables using kosis_search → Confirm orgId and tblId
2. Find region codes using kosis_region_code → Secure objL1 code
3. Retrieve actual data using kosis_get_data
```
> **Important:** KOSIS has different region code systems for each table (e.g., administrative division codes, SGG serial numbers, compressed codes). `kosis_region_code` automatically finds accurate codes using natural language.
### 1. Integrated Search (kosis_search)
Find statistical tables by keyword. First step to confirm `orgId` and `tblId`.
```
kosis_search({ keyword: "unemployment rate" })
```
**Parameters:**
- `keyword` (required): Search keyword
- `orgId`: Filter by organization code (e.g., `101` = National Statistical Office)
- `sort`: `RANK` (relevance) or `DATE` (newest)
- `count`: Number of results (default 10)
**Response Example:**
```
Table Name: Administrative District (Province)/Sex Unemployment Rate
Organization Code: 101
Table ID: DT_1DA7104S
```
### 2. Region Code Mapping (kosis_region_code)
Confirm region codes for specific statistics.
```
kosis_region_code({ tblId: "DT_1YL20631", region: "Incheon Seo-gu" })
```
**Response Example:**
```
Region: Incheon Metropolitan City, Seo-gu
Code (objL1): 23080
Usage: kosis_get_data({ orgId: "101", tblId: "DT_1YL20631", objL1: "23080" })
```
**Parameters:**
- `tblId` (required): Table ID
- `region` (required): Region name (e.g., `Incheon Seo-gu`, `Seoul Gangnam-gu`, `Namdong-gu`)
- `orgId`: Organization code (default 101)
> **Why is it necessary?** Even for the same region, codes differ across tables:
> - Registered population: `28260` (administrative division code)
> - Aged population ratio: `23080` (SGG serial code)
> - Unemployment rate (city, county): `2308` (compressed code)
### 3. Statistical Data Retrieval (kosis_get_data)
Retrieve actual numerical data using found `orgId` and `tblId`.
```
kosis_get_data({
orgId: "101",
tblId: "DT_1DA7104S",
objL1: "00", // Nationwide
objL2: "0", // Total
prdSe: "M", // Monthly
newEstPrdCnt: 3 // Recent 3 months
})
```
**Parameters:**
- `orgId` (required): Organization code
- `tblId` (required): Table ID
- `objL1`~`objL4`: Classification values (`ALL` = entire, `00` = nationwide, etc.)
- `itmId`: Item ID (`ALL` = entire)
- `prdSe`: Periodicity (`Y` = annual, `H` = semi-annual, `Q` = quarterly, `M` = monthly)
- `startPrdDe` / `endPrdDe`: Period range (e.g., `2020` ~ `2024`)
- `newEstPrdCnt`: Latest N periods (used when `startPrdDe` is not input)
**Response Example:**
```
Item: Unemployment Rate | Time: 202602 | Unit: % | Value: 3.4
```
> **Tip:** If errors occur with `objL` parameters, try adding `ALL` sequentially. Each table has a different classification structure. Confirm classification items using `kosis_table_info` for accuracy.
### 3. Statistical List Exploration (kosis_list)
Explore statistical lists by topic or organization.
```
# Top-level topic list
kosis_list({})
# Sublist under "Population"
kosis_list({ parentListId: "A" })
```
**Service View Codes:**
| Code | Description |
|------|------|
| `MT_ZTITLE` | Domestic Statistics (by topic) — default |
| `MT_OTITLE` | Domestic Statistics (by organization) |
| `MT_GTITLE01` | e-Local Indicators |
| `MT_GTITLE02` | e-National Indicators |
| `MT_RTITLE` | North Korean Statistics |
| `MT_ATITLE01` | International Statistics |
**Top-level topic IDs:**
| ID | Topic | ID | Topic |
|----|------|----|------|
| A | Population | J1 | General Economy · Business |
| B | General Social | K1 | Agriculture |
| C | Crime · Safety | L | Mining · Manufacturing |
| D | Labor | M1 | Construction |
| E | Income · Consumption · Assets | M2 | Transportation · Logistics |
| F | Health | O | Wholesale · Retail · Service |
| G | Welfare | P1 | Wage |
| H1 | Education · Training | P2 | Price |
| I1 | Housing | Q | National Accounts |
| I2 | Land Use | R | Government · Finance |
| S1 | Finance | T | Environment |
| S2 | Trade · Balance of Payments | V | Regional Statistics |
### 4. Statistical Metadata (kosis_meta)
Retrieve metadata such as purpose, legal basis, and periodicity.
```
kosis_meta({ orgId: "101", tblId: "DT_1DA7104S" })
```
**metaItm Options:** `All`, `statsNm`, `statsKind`, `statsContinue`, `basisLaw`, `writingPurps`, `statsPeriod`, `statisFrm`
### 5. Table Description (kosis_table_info)
Confirm table structure, classification items, units, and sources.
```
# Classification items
kosis_table_info({ orgId: "101", tblId: "DT_1DA7104S", type: "ITM" })
# Unit confirmation
kosis_table_info({ orgId: "101", tblId: "DT_1DA7104S", type: "UNIT" })
```
**type Options:**
| Code | Description |
|------|------|
| `TBL` | Table name (default) |
| `ORG` | Organization name |
| `PRD` | Publication information |
| `ITM` | Classification items |
| `CMMT` | Notes |
| `UNIT` | Unit |
| `SRC` | Source |
| `UPD` | Data update date |
### 6. Key Indicators (kosis_indicator)
Retrieve concepts, selection methods, and sources of key economic and social indicators.
```
kosis_indicator({ jipyoId: "DT_1B04005N" })
```
## Practical Examples
### Example 1: Recent 3 months of nationwide unemployment rate
```
1. kosis_search({ keyword: "unemployment rate" })
→ orgId: 101, tblId: DT_1DA7104S
2. kosis_get_data({
orgId: "101", tblId: "DT_1DA7104S",
objL1: "00", objL2: "0",
prdSe: "M", newEstPrdCnt: 3
})
→ 2025.12: 4.1% | 2026.01: 4.1% | 2026.02: 3.4%
```
### Example 2: Aged population ratio in Incheon Seo-gu (using region code mapping)
```
1. kosis_search({ keyword: "aged population ratio" })
→ orgId: 101, tblId: DT_1YL20631
2. kosis_region_code({ tblId: "DT_1YL20631", region: "Incheon Seo-gu" })
→ objL1: 23080
3. kosis_get_data({
orgId: "101", tblId: "DT_1YL20631",
objL1: "23080", itmId: "T10",
prdSe: "Y", newEstPrdCnt: 5
})
→ 2021: 11.4% | 2023: 12.4% | 2025: 14.3%
```
### Example 3: Registered population by year
```
1. kosis_search({ keyword: "registered population" })
→ orgId: 101, tblId: DT_1B04005N
2. kosis_get_data({
orgId: "101", tblId: "DT_1B04005N",
objL1: "00", objL2: "0", itmId: "T2",
prdSe: "Y", newEstPrdCnt: 3
})
→ 2023: 51,325,329 | 2024: 51,217,221 | 2025: 51,117,378
```
### Example 3: Exploring population-related statistical tables
```
1. kosis_list({})
→ A=Population, D=Labor, P2=Price ...
2. kosis_list({ parentListId: "A" })
→ A_4=Population Census, A_7=Registered Population Status, A_3=Population Trend Survey ...
3. kosis_list({ parentListId: "A_7" })
→ Detailed statistical table list
```
## Major Organization Codes
| Code | Organization Name |
|------|--------|
| 101 | National Data (formerly National Statistical Office) |
| 110 | Ministry of Interior and Safety |
| 115 | Ministry of Employment and Labor |
| 117 | Ministry of Land, Infrastructure and Transport |
| 118 | Ministry of Environment |
| 145 | Ministry of Education |
| 301 | Bank of Korea |
| 311 | Financial Supervisory Service |
| 354 | Korea Institute for Health and Social Affairs |
## Error Codes
| Code | Meaning | Solution |
|------|------|------|
| 10 | Authentication key error | Check KOSIS_API_KEY |
| 20 | Missing required parameter | Add objL value as ALL |
| 21 | Incorrect parameter | Confirm valid value using kosis_table_info |
| 31 | Over 40,000 cells | Narrow classification/period range and re-query |
## Testing
```bash
npm test
```
Automatically checks 26 items (server initialization, tool registration, search, region code mapping, data retrieval, list exploration, table description).
### Reusable Test Harness
`test/harness.ts` is a **universal test framework** that can be reused across MCP servers.
To apply to another MCP project:
1. Copy `test/harness.ts`
2. Write MCP-specific test scenarios in `test/run.ts`
3. Run using `npm test`
```typescript
import { McpTestHarness } from "./harness.js";
const harness = new McpTestHarness("build/index.js", {
MY_API_KEY: "..."
});
await harness.start();
// Tool list verification
const tools = await harness.listTools();
// Tool call test
const result = await harness.callTool("my_tool", { param: "value" });
console.log(result.text, result.isError);
await harness.stop();
```
Actually, [local-finance-mcp](https://github.com/simonsez9510/local-finance-mcp) uses the same harness.ts to configure 32 tests.
## License
MIT
