This MCP server (with a matching CLI) searches, retrieves, and exports Korean national statistics (KOSIS) via OpenAPI, handling the API's many pitfalls automatically.
Connect & learn: kosis_status checks the API key with a live round-trip; kosis_guide documents service views, cycles, meta kinds, error codes, limits, and pitfalls.
Find tables: kosis_search does integrated keyword search (e.g., '사교육비'), and kosis_list walks the statistics-list tree by topic or organization.
Inspect metadata: kosis_meta returns item (ITM), period (PRD), source, and comments; kosis_explain returns the statistical description (survey overview).
Fetch figures: kosis_data returns numeric values (time × classification × item → value), auto-splitting periods to bypass the 40,000-cell limit and auto-matching classification axes (obj_l1–obj_l8) for multi-axis tables.
Export data: kosis_collect saves results to xlsx, csv, json, or sqlite with variable column layouts.
Cite tables: kosis_citation projects a table into bibliographic fields (survey-level container_title vs. table-level title), optionally with access date.
Indicators (separate series): kosis_indicator_search finds curated key indicators with full paging, and kosis_indicator_data fetches time-series values, filtering all periods client-side since the server ignores the date range.
Robustness: distinguishes 0-result (err 30) from failure, reports truncation instead of silently cutting, and surfaces confirmed axis counts via meta.obj_levels.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type @ followed by the MCP server name and your instructions, e.g., "@io.github.rubatoyd/kosis-openapi-mcp Retrieve the consumer price index by month from 2020 to 2025 and export to xlsx"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
📈 사용량 — 최근 14일 조회 0회(고유 0) · 클론 0회(고유 0) · 릴리스 자산 누적 다운로드 15
2026-09-12 자동 갱신 · 전체 이력은
docs/usage.csv. GitHub 트래픽 통계는 14일 창만 제공하므로 이 저장소가 매일 찍어 누적한다.
KOSIS(국가통계포털) 공유서비스 OpenAPI 를 검색·수집하는 MCP 서버 + CLI.
통계표를 찾고, 항목·분류·주기를 확인하고, 수치를 받아 xlsx·csv·json·sqlite 로 내보낸다. 4만 셀 제한에 걸리면 기간을 알아서 쪼개 전수를 회수한다.
자매 저장소: law-openapi-mcp(법제처) · na-openapi-mcp(국회도서관) · nl-openapi-mcp(국립중앙도서관) · kci-openapi-mcp · scienceON-mcp
통계 그 자체다. 표의 메타(작성기관·조사명·수록기간·주기)와 수치(시점 × 분류 × 항목 → 값)를 도메인 그대로 준다.
서지·인용 형식은 부가 기능(kosis_citation)으로 따로 두었다. 서지관리 도구로
넘길 때만 쓰면 되고, 그 도구가 아는 유형 목록이 통계 응답의 모양을 바꾸지는 않는다.
Related MCP server: korean-stat-mcp
인증키 하나. kosis.kr 회원가입 후 공유서비스 활용신청(자동 승인).
cp .env.example .env # KOSIS_API_KEY=... 를 채운다🔴 발급된 값을 그대로 넣으세요. base64 처럼 보여도(끝이
=) 디코드하면err 11(유효하지 않은 인증키)이 납니다.
uv sync
uv run kosis status
uv run kosis search 사교육비
uv run kosis meta --org 101 --tbl DT_1PE201 --kind ITM # 항목 ID 확인
uv run kosis data --org 101 --tbl DT_1PE201 --prd Y --start 2020 --end 2025
uv run kosis collect --org 101 --tbl DT_1B040A3 --prd M --start 202101 --end 202512
# 분류축이 여럿인 표도 그대로 — 축 개수는 알아서 맞춘다(산업 × 규모)
uv run kosis data --org 118 --tbl DT_118N_MON051 --prd H --start 202401 --end 202401
# 주요지표(통계표와 다른 계열) — 표 구조를 몰라도 값까지 바로
uv run kosis indicator 출산율
uv run kosis indicator-data --id 13 --start 2020 --end 2025MCP 등록:
{
"mcpServers": {
"kosis": {
"type": "stdio",
"command": "uvx",
"args": ["--from", "git+https://github.com/rubatoyd/kosis-openapi-mcp", "kosis-mcp"],
"env": { "KOSIS_API_KEY": "발급받은_값_그대로" }
}
}
}PyPI 에 올린 패키지가 아직 없어 저장소에서 바로 받아 쓴다(자매 저장소와 같은 방식).
main의 HEAD 를 쓰므로 다음 기동에 최신이 반영된다.
도구 | 하는 일 |
| 인증키 보유 여부 + 실제 왕복 1회 |
| 서비스뷰·주기·메타 종류·오류코드·한계·함정 |
| 통계표 찾기(통합검색) |
| 통계목록 트리 한 단계(주제별·기관별 …) |
| 표의 항목(ITM)·분류(NCD)·주기(PRD)·출처 등 |
| 통계설명(조사개요) |
| 수치 — 4만 셀 초과 시 기간 자동 분할 |
| 표를 서지 칸으로 투영(부가 기능) |
| 수치를 xlsx/csv/json/sqlite 로 저장 |
| 주요지표 찾기(통계표와 다른 계열) — 페이징 전수 회수 |
| 주요지표의 시점별 수치 — 서버가 안 거르는 시점을 대신 거른다 |
172쪽짜리 공식 개발가이드가 있는데도 가장 중요한 셋이 그 안에 없거나 틀리다:
🔴 jsonVD=Y 가 없으면 JSON 이 아니다 — 키에 따옴표가 없는 자바스크립트 객체
리터럴이 온다. 이 파라미터는 가이드의 입력 변수 표에 없고 JSP 예제 안에만 있다.
🔴 통계자료를 orgId/tblId 로 부르려면 /openapi/Param/statisticsParameterData.do
를 써야 한다. 가이드가 표를 실어 둔 statisticsData.do 로 보내면 항상 err 20.
🔴 인증키를 디코드하지 말 것.
그 밖에:
🔴 분류축(objL) 개수가 표의 축 수와 정확히 맞아야 한다 — 모자라면 err 20 (objL),
넘치면 err 21. 그런데 축 개수를 알려 주는 메타 서비스가 없다(NCD 는 분류가 아니라
신규수록 시점이고 OBJ·CLS 는 err 30). kosis_data 가 축을 하나씩 늘려 맞추므로
다축 표(예: 산업 × 규모)도 그냥 부르면 된다 — 확정된 축은 meta.obj_levels 에 실린다.
모든 실패가 HTTP 200 이다. 성공은 배열, 실패는 {err, errMsg} 객체.
Content-Type 은 둘 다 text/html 이라 믿을 수 없다.
err 30(결과 없음)은 오류가 아니다 — 0건과 실패를 구분해서 보고한다.
요청당 4만 셀(err 31) · 분당 200건(err 40).
페이징이 없다 — 통합검색·목록·통계자료는 서버가 준 만큼이 전부다(조용히 자르지 않고 알린다).
단 통계주요지표 계열만 예외로 pageNo·numOfRows 를 받고 안 주면 10건에서 잘린다 —
kosis_indicator_* 가 끝까지 넘겨 전수를 회수한다(docs §7).
🔴 주요지표 계열은 시점 범위를 거르지 않는다(모드 스위치일 뿐 값은 무시된다).
kosis_indicator_data 가 전 구간을 받아 직접 거르고 meta.server_filtered=false 로 알린다.
parentListId 는 필수라고 적혀 있지만 생략하면 최상위가 온다.
자세한 근거와 재현 방법은 docs/KOSIS_API_GUIDE.md.
MIT
통계표 하나를 서지(인용) 칸으로 투영한다 — 선택 기능.
⚠️ 이 도구는 부가 기능이다. 통계를 쓰는 것이 목적이면 kosis_search(표 메타)와
kosis_data(수치)가 본령이고, 이 도구는 서지관리 도구로 넘길 때만 쓴다.
KOSIS 는 조사(STAT_NM)와 표(TBL_NM) 두 층을 다 주므로 어느 층으로 인용할지는
부르는 쪽이 고른다 — container_title 이 조사층, title 이 표층이다.
Args: accessed: 조회일자(YYYY-MM-DD). 데이터셋 인용에는 조회일자가 필요하다.
| Name | Required | Description | Default |
|---|---|---|---|
| org_id | Yes | ||
| tbl_id | Yes | ||
| accessed | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No usable annotation flags are verifiable in this context, so the description carries the transparency burden. It adds genuine behavioral context: the KOSIS two-layer (STAT_NM/TBL_NM) structure, the caller-driven layer choice, and the accessed-date requirement for dataset citations. However, it never states what the tool returns (citation string? formatting?), whether the operation is pure/read-only, or any failure behavior — gaps for a tool with no output schema.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Purpose is front-loaded, and the ⚠️ block economically steers the agent away from overuse by naming alternatives. The layer-semantics paragraph is the longest section but is justified because it determines citation structure. The trailing Args line is minimal; each sentence earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a 3-parameter, no-nested, no-output-schema tool, the description covers purpose, usage conditions, and layer semantics well. But because no output schema exists, the description should explain the return value, and it does not; two of three parameters also remain under-documented. Adequate for a simple auxiliary tool, with clear gaps.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description must document parameters; it explicitly covers only 'accessed' (YYYY-MM-DD and why it is needed). The two-layer discussion indirectly hints at what 'id' refers to (a table or survey), but the 'style' parameter is never mentioned and no enum/default guidance exists — a meaningful gap for a citation-formatting tool.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific verb and resource: '통계표 하나를 서지(인용) 칸으로 투영한다' — projecting one statistical table into a citation field, explicitly marked as an auxiliary feature. It also names sibling tools (kosis_search for metadata, kosis_data for numbers) as the mainline, which differentiates this tool without requiring an agent to open other schemas.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Gives explicit when-to-use (only when handing off to a bibliographic management tool) and when-not-to (when the goal is using statistics, kosis_search and kosis_data are the main tools). It further instructs the caller to choose the citation layer — container_title for the survey layer, title for the table layer — leaving no ambiguity about selection criteria.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
통계표 수치를 받아 xlsx/csv/json/sqlite 로 저장한다.
⚠️ 분류 축이 표마다 다르므로 열 구성이 가변이다 — 분류 이름이 그대로 열이 된다.
축 개수도 표마다 다르지만 obj_l2~obj_l8 을 비워 두면 자동으로 맞춘다.
| Name | Required | Description | Default |
|---|---|---|---|
| end | No | ||
| name | No | kosis | |
| items | No | ALL | |
| start | No | ||
| obj_l1 | No | ALL | |
| obj_l2 | No | ||
| obj_l3 | No | ||
| obj_l4 | No | ||
| obj_l5 | No | ||
| obj_l6 | No | ||
| obj_l7 | No | ||
| obj_l8 | No | ||
| org_id | Yes | ||
| prd_se | Yes | ||
| recent | No | ||
| tbl_id | Yes | ||
| formats | No | ||
| out_dir | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate readOnlyHint=false, openWorldHint=true, and destructiveHint=false. The description adds useful behavior: saving to files, variable column structure, and auto-adjustment of axes. However, it does not disclose other behaviors such as file overwriting, authentication requirements, or rate limits. It adds some value beyond annotations but is not comprehensive.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise with two sentences. The first sentence states the main purpose, and the second warns about variable columns. It is efficient and front-loaded, though the second sentence is a bit long and could be split for clarity.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's complexity (18 parameters, no output schema, no enums), the description is far from complete. It does not explain required parameters like org_id, tbl_id, or prd_se, nor optional ones like start/end/recent. The warning about variable columns is helpful, but the overall context is insufficient for an agent to call the tool correctly without further investigation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description must compensate. It explains obj_l2~obj_l8 auto-adjustment and the formats parameter implicitly (xlsx/csv/json/sqlite). However, it leaves the other 14 parameters (org_id, tbl_id, prd_se, start, end, recent, name, items, obj_l1) undocumented. This is a significant gap for a tool with 18 parameters.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a clear verb+resource: receives statistics table values and saves them as xlsx/csv/json/sqlite. It also mentions the variable column structure, but does not differentiate from sibling tools like kosis_data or kosis_indicator_data, which may also fetch data. The purpose is specific but not distinguished from alternatives.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance on when to use this tool vs alternatives. It provides a technical note about variable columns and auto-adjustment, but does not state when this tool is preferred over siblings like kosis_data. The agent is left to infer usage from the name and description.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
통계표의 수치를 받는다.
🔴 분류축이 여럿인 표(예: 산업 × 규모)도 그냥 부르면 된다. KOSIS 는 요청의
분류축 개수가 표의 축 개수와 정확히 맞기를 요구하는데(모자라면 err 20 (objL),
넘치면 err 21) 축 개수를 알려 주는 메타가 없다. 그래서 이 도구가 축을 하나씩
늘려 가며 맞춘다 — 결과의 meta.obj_levels 에 확정된 축이 실린다.
Args:
org_id: 기관 ID(예: '101').
tbl_id: 통계표 ID(예: 'DT_1B040A3').
prd_se: 수록주기 — Y(년)·H(반기)·Q(분기)·M(월)·D(일). kosis_meta(kind='PRD') 로 확인.
start, end: 시점 범위(예: '202101''202512'). 🔴 이 방식이면 4만 셀을 넘어도
자동으로 기간을 쪼개 전수를 받는다.
recent: 최근 N개 시점. start/end 대신 쓴다(이 방식은 자동 분할이 안 된다).
obj_l1: 분류1 — 'ALL' 전체, '11' 특정, '11*' 하위 전체, '11+21' 여럿.
obj_l2 ~ obj_l8: 분류28. 비워 두면 필요한 만큼 'ALL' 로 자동으로 채운다.
4만 셀(err 31)에 걸릴 때 특정 코드로 좁히는 자리이기도 하다.
items: 항목 — 'ALL' 또는 항목 ID(kosis_meta(kind='ITM')).
max_rows: 돌려줄 최대 행 수(파일로 받으려면 kosis_collect).
| Name | Required | Description | Default |
|---|---|---|---|
| end | No | ||
| items | No | ALL | |
| start | No | ||
| obj_l1 | No | ALL | |
| obj_l2 | No | ||
| obj_l3 | No | ||
| obj_l4 | No | ||
| obj_l5 | No | ||
| obj_l6 | No | ||
| obj_l7 | No | ||
| obj_l8 | No | ||
| org_id | Yes | ||
| prd_se | Yes | ||
| recent | No | ||
| tbl_id | Yes | ||
| max_rows | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description richly discloses behaviors beyond annotations: it explains automatic axis-count matching (with error codes 20/21), automatic period splitting for >40,000 cells, auto-filling of obj_l2-8 with 'ALL', and the presence of meta.obj_levels in the result. It also notes the 40,000-cell limit (err 31). These are valuable behavioral traits not covered by the readOnlyHint/openWorldHint annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured: a one-line summary, a highlighted note about classification axes, then a bulleted Args list. Key behaviors are front-loaded with red emojis to draw attention. Every sentence adds value—no fluff or repetition. It is detailed but efficiently organized.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the complexity (16 params, no output schema, no enums), the description is remarkably complete. It covers error conditions, parameter relationships, alternatives, and behavioral nuances. It mentions the result's meta.obj_levels, which gives insight into the return structure. An agent can reliably call this tool correctly without additional documentation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With 0% schema description coverage, the description fully compensates by documenting all 16 parameters. It explains each parameter's purpose, format (e.g., '101' for org_id, 'DT_1B040A3' for tbl_id), valid values (Y/H/Q/M/D for prd_se), and special behaviors (wildcards like '11*', multiple codes '11+21', and auto-fill logic). This is exceptional given the schema provides no help.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with a clear, specific verb and resource: 'Gets the numbers of a statistical table.' This unambiguously states the tool's purpose and inherently distinguishes it from siblings like kosis_meta (metadata) and kosis_search. It is not a tautology and adds concrete scope.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides explicit alternatives: it directs users to kosis_collect for file retrieval and to kosis_meta for validating prd_se and items. It also explains when to use start/end vs recent and the auto-fill behavior for obj_l2-8. However, it does not explicitly contrast with kosis_indicator_data, a sibling that might overlap, so it stops short of a perfect 5.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
통계설명(조사개요) — 목적·근거·주기·범위 등.
통계표에는 초록이 없으므로, 관련도 채점이나 요약이 필요할 때 이 설명이 재료다.
| Name | Required | Description | Default |
|---|---|---|---|
| org_id | Yes | ||
| tbl_id | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint and openWorldHint, so the safety profile is covered. The description adds content-level behavior by listing what the explanation contains, but it does not discuss return format or limitations. This is acceptable given the annotation coverage.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two short sentences with no fluff; the resource type comes first and the usage rationale second. It is concise and front-loaded, though the second sentence is somewhat indirect.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple two-parameter read-only tool, the description covers return content and one use case. However, there is no output schema and no explanation of parameter semantics, so an agent cannot fully infer invocation details from this description alone.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0% and the description does not explain org_id or tbl_id formats, provenance, or how to obtain them. The parameter names are somewhat self-explanatory, but the description fails to compensate for the lack of schema documentation.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description states that the tool provides statistical explanation/survey overview with purpose, basis, period, and scope. This is specific enough to identify the tool's resource and distinguish it from generic data or status siblings, though it does not explicitly contrast with kosis_meta.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
It gives a clear usage context: statistical tables lack abstracts, so this explanation is material when relevance scoring or summarization is needed. It does not mention exclusions or alternatives, but the intended use case is explicit.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
이 API 를 쓸 때 알아야 할 것 — 서비스뷰·주기·메타 종류·한계·함정.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint and openWorldHint. The description adds useful behavioral context by listing limitations and pitfalls, signaling that this is a meta/orientation resource rather than a data-returning operation.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single front-loaded phrase with a compact list of covered topics. There is no wasted wording or redundancy with the schema or annotations.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a no-parameter, read-only guide tool, the description is reasonably complete: it states what knowledge areas it covers and flags limitations and pitfalls. It does not describe the response format, but no output schema exists and the tool's purpose as a guide makes that less critical.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema is empty with 0 parameters and 100% schema coverage, so there are no parameter semantics for the description to clarify. A baseline of 4 is appropriate because no parameter documentation is needed.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description states this tool provides the knowledge needed to use the KOSIS API, specifically covering service view, cycle, meta types, limitations, and pitfalls. This is clear as a guide/resource, but it does not explicitly differentiate itself from siblings like kosis_explain.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The phrase 'what to know when using this API' implies the agent should consult this guide alongside or before the other kosis_* tools, but no explicit when-to-use or when-not-to-use guidance is given. Alternatives are not named or excluded.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
주요지표의 시점별 수치를 받는다.
🔴 KOSIS 가 이 계열에서는 시점 범위를 거르지 않는다. startPrdDe/endPrdDe 는
값이 무시되고 모드 스위치로만 작동해서, 무엇을 주든 전 구간이 온다(실측).
그래서 이 도구가 전 구간을 받아 직접 거르고, 그 사실을 meta.server_filtered
(=false)와 meta.filter_note 로 알린다 — 서버가 걸러 줬다고 믿으면 요청하지
않은 구간을 받고도 모른다.
Args:
jipyo_id: 지표ID(kosis_indicator_search 로 찾는다).
start, end: 시점 범위(예: '2015'~'2025'). 비우면 전 구간.
recent: 최신 N개 시점만(start/end 를 안 줬을 때).
| Name | Required | Description | Default |
|---|---|---|---|
| end | No | ||
| start | No | ||
| recent | No | ||
| jipyo_id | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description prominently discloses that the server does not filter by time range, that the tool filters locally, and that the outcome is reported via meta.server_filtered=false and meta.filter_note. This is valuable behavioral information beyond the readOnlyHint annotation and contradicts nothing.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The purpose is stated first, followed by a justified warning and a clean Args list. The warning is slightly long but contains essential caveats needed for correct usage, so it earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description provides all necessary input semantics, the critical filtering caveat, and mentions relevant metadata keys. Since there is no output schema, the absence of output format details is acceptable; the tool can be used correctly with the given information.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema provides zero parameter descriptions, but the description explains all four parameters: jipyo_id, start, end, and recent, including the special meaning of start/end as mode switches rather than true server-side filters. This fully compensates for the schema's lack of documentation.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool retrieves time-series values for major indicators by jipyo_id, and references kosis_indicator_search for finding the ID. It is specific enough to distinguish the resource, though it does not explicitly differentiate it from sibling data tools like kosis_data.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives practical usage instructions: start/end range examples, behavior when empty, and recent usage with constraints. It also warns about server-side filtering behavior. However, it does not explicitly state when to use this tool versus the other sibling data tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
주요지표를 이름으로 찾는다 — 통계표와는 다른 계열이다.
KOSIS 는 통계표(TBL_ID) 말고 지표(statJipyoId) 계열을 따로 둔다(합계출산율,
추계인구 …). 표 구조를 몰라도 바로 값을 볼 수 있는 대신, 지표로 큐레이션된 것만
있다. 표 단위로 파고들 거라면 kosis_search 를 쓴다.
🔴 이 계열에만 페이징이 있고 안 주면 서버가 10건에서 자른다 — 이 도구가 끝까지
넘겨 전수를 회수한다(meta.pages 에 몇 쪽을 읽었는지 실린다).
Args: name: 지표명(예: '출산율', '인구'). jipyo_id: 지표ID 로 직접 찾을 때(둘 중 하나는 필요). max_records: 돌려줄 최대 건수.
| Name | Required | Description | Default |
|---|---|---|---|
| name | No | ||
| jipyo_id | No | ||
| max_records | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The readOnlyHint and openWorldHint annotations already signal safety, and the description adds meaningful behavior: it auto-paginates through all pages and reports pages read in meta.pages. No side effects are claimed, so there is no contradiction with the annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is compact and well structured, with a purpose statement, a usage distinction, a pagination warning, and an Args list. It is slightly repetitive in emphasizing the indicator-vs-table distinction, but all sentences carry useful information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description covers key usage context and pagination, but with no output schema it does not describe the returned item fields or structure beyond meta.pages. An agent would still need to infer what an indicator result object contains and how to use the returned IDs with related tools.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Although the schema has no descriptions, the Args section explains all three parameters: name with examples, jipyo_id as a direct-ID alternative, and max_records as the maximum number of returned items. It also clarifies that either name or jipyo_id should be supplied, which is important operational guidance.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's purpose: finding major KOSIS indicators by name, and explicitly distinguishes this from the statistical-table series. It also names the sibling tool kosis_search for table-oriented searches, so an agent can disambiguate immediately.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
It gives concrete guidance: use kosis_search instead when working at the table level, and explains that indicator results are curated. It also describes pagination behavior, though it does not explicitly mention when to use kosis_indicator_data instead of this search tool.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
통계목록 트리를 한 단계 훑는다(주제별·기관별 등).
Args:
vw_cd: 서비스뷰 코드. kosis_guide 의 서비스뷰 참조.
parent_id: 상위 목록 ID. 비우면 최상위가 온다(개발가이드는 필수라 하지만
실제로는 생략 가능 — 실측).
| Name | Required | Description | Default |
|---|---|---|---|
| vw_cd | No | MT_ZTITLE | |
| parent_id | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare this as read-only and non-destructive. The description adds useful behavioral detail beyond that: traversal is one step at a time, empty parent_id returns top-level items, and an empirical note contradicts the development guide's claim that parent_id is required. It does not describe return shape, but that is minor for a simple read-only list tool.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is compact and efficiently structured: a one-sentence purpose statement followed by a concise argument list. There is no filler, and the empirically grounded note about parent_id earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a two-parameter, read-only listing tool, the description covers purpose, parameter semantics, and key call behavior. It does not explicitly describe the return format, but the nature of a one-level tree scan makes it reasonably inferable, and the annotations cover the safety profile.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 0%, so the description carries the full parameter-documentation burden. Both parameters are meaningfully explained: vw_cd is tied to the service-view definitions in kosis_guide, and parent_id's optionality and empty-value behavior are explicitly clarified.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific action ('scans one level of the statistics list tree') and a clear resource, optionally scoped by topic or institution. It is clearly not tautological and conveys the tool's basic function, but it does not explicitly differentiate it from sibling tools such as kosis_search or kosis_meta.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The context of use is implied: browse the statistics list hierarchy one level at a time, and leave parent_id empty to get the top level. However, the description never states when to prefer this tool over its siblings, nor does it mention any exclusions or alternative tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
통계표의 메타자료 — 항목(ITM)·수록기간(PRD)·출처(SOURCE)·주석(CMMT) 등.
⚠️ kosis_data 를 부르기 전에 ITM 으로 항목 ID 를, PRD 로 수록주기를 확인하면
err 20/21 을 피할 수 있다.
🔴 분류축을 알려 주는 종류는 없다. NCD 는 분류가 아니라 신규수록 시점이고
OBJ·CLS 는 err 30 이다(실측) — 축은 kosis_data 가 알아서 맞춘다.
⚠️ 없는 kind 는 err 21 이 아니라 err 30(0건)으로 오므로 오타가 '자료 없음'처럼
보인다. 그래서 아는 종류만 받는다 — 가능한 값은 kosis_guide 의 메타_종류.
| Name | Required | Description | Default |
|---|---|---|---|
| kind | No | TBL | |
| org_id | Yes | ||
| tbl_id | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Beyond the readOnlyHint annotation, the description discloses specific error behaviors (err 20/21 vs. err 30), what kinds are not supported (NCD, OBJ, CLS), and that axes are automatically handled by kosis_data. This adds meaningful behavioral context.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is dense but well-organized, front-loading the main purpose then listing crucial warnings. Each sentence contributes actionable information, and the use of emojis aids scannability without adding fluff.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a metadata-lookup tool with no output schema, the description covers all essential context: what it returns, relationship to sibling tools, error semantics, and limitations. It is complete enough for an agent to decide when and how to use it.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The description explains the 'kind' parameter and its accepted values (from kosis_guide) and its default, but does not elaborate on org_id or tbl_id. Since these are self-explanatory in context and the schema covers them implicitly, the description adds moderate semantic value beyond the raw schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states that the tool retrieves metadata (items, periods, sources, comments) for a statistical table, distinguishing it from data retrieval. It is specific about the resource and the scope of information provided.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly instructs to call this tool before kosis_data to check ITM and PRD to avoid errors 20/21, and warns about the absence of classification-axis kinds and the error behavior of unknown kinds. It also points to kosis_guide for possible kind values, providing clear when-to-use and when-not-to-use guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
통계표를 이름·내용으로 찾는다(KOSIS 통합검색).
Args: query: 검색어(예: '사교육비', '출산율'). max_records: 돌려줄 최대 건수.
| Name | Required | Description | Default |
|---|---|---|---|
| query | Yes | ||
| max_records | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already provide readOnlyHint and openWorldHint, so the description need not restate safety. It adds useful behavioral specifics: search scope is by name/content and max_records caps the result count. It does not describe output shape or pagination, but for a simple read-only search this is a minor gap with no contradiction.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is compact and front-loaded: one sentence states purpose and a short Args block defines the parameters. There is no filler, repetition, or unnecessary detail.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a two-parameter read-only search tool with helpful annotations, the description covers the essential invocation details: what is searched, how to phrase the query, and the result cap. The only notable absence is a pointer to sibling tools for alternative use cases, but the simple scope and annotations make the definition sufficiently complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, but the description fully compensates by clearly defining query as the search term with concrete examples and max_records as the maximum number of results to return. Both parameters receive meaning beyond their bare schema titles.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific action ('찾는다/finds') and resource ('통계표/statistical tables'), and specifies the search is by name or content. It is clear but does not explicitly distinguish it from sibling tools such as kosis_list or kosis_meta, so it falls just short of full differentiation.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The examples (e.g., '사교육비', '출산율') and 'KOSIS 통합검색' imply this is for finding tables by keyword, giving some contextual guidance. However, there is no explicit statement about when to use this tool versus the sibling tools or when not to use it.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
연결 점검 — 인증키 보유 여부 + KOSIS 실제 왕복 1회.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Beyond the readOnlyHint and openWorldHint annotations, the description discloses meaningful behavioral traits: it checks authentication-key possession and performs one live network round trip to KOSIS. This reveals the external dependency, latency, and auth-relevant behavior, which are valuable for the agent to anticipate.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The entire description is one short, front-loaded sentence that conveys the tool's purpose and behavior with no filler. Every part of the description adds information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a zero-parameter status-check tool with no output schema, the description is largely complete: it says what is checked and that a live network call occurs. The only minor gap is that it does not specify the exact return format, but this is low-impact for such a simple tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool has zero parameters and schema coverage is 100%, so the baseline of 4 applies. The description does not need to explain parameter meanings since there are none.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific verb and resource: '연결 점검' (connection check) for KOSIS, and specifies two concrete checks: whether an API key is held and whether one actual round trip works. This clearly distinguishes the status tool from siblings like kosis_data, kosis_search, or kosis_explain.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description clearly implies when to use the tool: when an agent needs to verify KOSIS connectivity or API key validity before relying on other KOSIS operations. It does not explicitly name alternatives, but none of the sibling tools serve this health-check role, so the context is sufficient.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
kosis_collect7 fields changedInput schema / properties / obj_l2Added value: +{
+ "default": "",
+ "title": "Obj L2",
+ "type": "string"
+}Input schema / properties / obj_l3Added value: +{
+ "default": "",
+ "title": "Obj L3",
+ "type": "string"
+}Input schema / properties / obj_l4Added value: +{
+ "default": "",
+ "title": "Obj L4",
+ "type": "string"
+}Input schema / properties / obj_l5Added value: +{
+ "default": "",
+ "title": "Obj L5",
+ "type": "string"
+}Input schema / properties / obj_l6Added value: +{
+ "default": "",
+ "title": "Obj L6",
+ "type": "string"
+}Input schema / properties / obj_l7Added value: +{
+ "default": "",
+ "title": "Obj L7",
+ "type": "string"
+}Input schema / properties / obj_l8Added value: +{
+ "default": "",
+ "title": "Obj L8",
+ "type": "string"
+}kosis_data7 fields changedInput schema / properties / obj_l2Added value: +{
+ "default": "",
+ "title": "Obj L2",
+ "type": "string"
+}Input schema / properties / obj_l3Added value: +{
+ "default": "",
+ "title": "Obj L3",
+ "type": "string"
+}Input schema / properties / obj_l4Added value: +{
+ "default": "",
+ "title": "Obj L4",
+ "type": "string"
+}Input schema / properties / obj_l5Added value: +{
+ "default": "",
+ "title": "Obj L5",
+ "type": "string"
+}Input schema / properties / obj_l6Added value: +{
+ "default": "",
+ "title": "Obj L6",
+ "type": "string"
+}Input schema / properties / obj_l7Added value: +{
+ "default": "",
+ "title": "Obj L7",
+ "type": "string"
+}Input schema / properties / obj_l8Added value: +{
+ "default": "",
+ "title": "Obj L8",
+ "type": "string"
+}kosis_indicator_datakosis_indicator_searchv0.1.0kosis_citationkosis_collectkosis_datakosis_explainkosis_guidekosis_listkosis_metakosis_searchkosis_statusScored across 11 tools
Each tool has a single clear role: table search vs indicator search, table data vs indicator data, metadata vs survey explanation, data retrieval vs file export. The detailed descriptions explicitly distinguish the similar indicator/table families, so an agent can reliably choose between them.
All tools share the kosis_ prefix and snake_case, and the search/data pairs are parallel (kosis_search/kosis_indicator_search, kosis_data/kosis_indicator_data). However, the second part mixes bare verbs (search, list, explain, collect) with bare nouns (meta, data, citation, guide), so it is not a strict verb_noun convention.
11 tools is well within the ideal range and each one earns its place: status/guide for orientation, search/explain/list/meta/data for the table workflow, indicator_search/indicator_data for the indicator workflow, plus collect and citation for output and scholarship.
For a read-only statistical data API, the surface is complete: users can discover tables by search or tree, read survey descriptions and table metadata, fetch full table data with automatic axis/period handling, access major indicators, export to files, and generate citations. No obvious dead ends or missing core operations remain.
Search and query 1,500+ OECD statistical datasets via SDMX. Keyless.
Access Korea’s G2B procurement and Nara Market data for bid notices, awards, contracts, statistics…
Find official Korean public datasets, agency-site menus, disclosure listings, and source URLs.
Powerful OpenDART API-based Korean corporate disclosure tools for accounting professionals