ecos 사용 가이드

한국은행 ECOS(경제통계시스템)에서 거시경제 지표를 조회합니다. Claude에게 자연어로 부탁하면 됩니다 — “GDP 추이 알려줘”, “기준금리와 환율 요약해줘”처럼요. 터미널 명령을 직접 입력할 필요는 없습니다.

---

사전 준비 — API 키 발급#

ECOS 스킬은 한국은행 ECOS Open API 키가 필요합니다.

1. 한국은행 경제통계시스템 ECOS Open API에서 회원가입
2. Open API → 인증키 신청 → 사용 목적·서비스명 입력 후 제출 → 즉시 발급 (별도 대기 없음)
3. 발급받은 키를 Claude Desktop 지침에 추가합니다 — Claude Desktop → 설정 → 일반 → “Claude 지침” 에 아래 한 줄을 붙여넣고 저장하세요.

ECOS_API_KEY=발급받은_키

자세한 가입·키 발급 절차는 ECOS 발급 가이드를 참고하세요.

한 번 넣으면 이후 모든 대화에서 Claude가 자동으로 사용합니다 — .env 같은 파일을 직접 만들 필요가 없습니다.

개발자라면 작업 폴더 루트의 .env에 같은 한 줄을 넣어도 됩니다.

인증키는 즉시 발급되므로 마감 직전에도 신청할 수 있습니다. 단, 첫 호출 시 수 분간 일시적으로 미반영될 수 있으니 여유를 두세요.

---

자주 쓰는 요청#

하고 싶은 것	이렇게 말하세요
핵심 지표 요약	”한국은행 100대 경제지표 보여줘”
GDP 추이	”최근 5년간 GDP 추이 정리해줘”
금리·환율	”기준금리와 환율 요약해줘”
물가	”CPI 추이 분기별로 가져와”
특정 지표	”소비자물가지수 2020년부터 2024년까지 연도별로 표로 정리해줘”
용어 정의	”GDP디플레이터 용어 정의 가져와서 각주로 넣어줘”

---

활용 시나리오#

거시경제 지표 시계열 조회#

보고서·사업계획서 본문에 인용할 GDP·CPI·기준금리 같은 지표를 기간을 지정해 가져옵니다.

최근 5년간 소비자물가지수를 연도별로 표로 정리해줘

분기별 데이터가 필요하면 기간과 주기를 함께 말해주세요.

2020년 1분기부터 2024년 4분기까지 GDP를 분기별로 가져와

100대 경제지표 요약#

한국은행이 선정한 핵심 지표를 한 번에 조회해 요약본을 만듭니다.

한국은행 100대 경제지표 중 금리 관련 항목만 뽑아줘

경제 용어 각주 생성#

보고서에 등장한 전문용어를 공식 정의로 각주 처리합니다.

"GDP디플레이터" 용어 정의 가져와서 각주로 넣어줘
"기준금리" 공식 정의 알려줘

---

출력 형식 지정#

출력 형식을 자연어로 함께 말하면 그에 맞게 정리해 줍니다.

원하는 형식	이렇게 말하세요
사람이 읽기 좋은 표	”표로 정리해줘”
숫자 배열(차트용)	“차트 그릴 수 있게 숫자 배열로 뽑아줘”

---

팁#

• 통계 코드를 몰라도 됩니다. 스킬이 자연어 요청을 보고 적절한 통계표를 자동으로 찾아 조회합니다. 다만 조회 결과가 의도와 다르면 “소비자물가지수(CPI)로 다시 조회해줘”처럼 좀 더 구체적으로 말해주세요.
• 기간·주기를 함께 말해주세요. “2020년부터 2024년까지 연도별로”처럼 기간과 주기를 함께 말하면 더 정확하게 조회합니다. 분기별이면 “분기별로”, 월별이면 “월별로”라고 말하면 됩니다.
• 보고서에 바로 붙여넣기. “표로 정리해줘”라고 하면 노션·Obsidian·README에 그대로 붙여넣을 수 있는 마크다운 표 형식으로 돌려줍니다.
• 용어 각주 자동화. 보고서 전문용어를 공식 정의로 한꺼번에 각주 처리할 수 있습니다.

---

안 될 때#

증상	원인 / 해결
”API 키가 없다”는 안내 (INFO-100)	Claude 지침(또는 .env)에 ECOS_API_KEY가 없거나 키가 비어 있음. 위 “사전 준비” 확인
”통계표를 찾을 수 없습니다”	요청한 지표가 ECOS에 없거나 표현이 달라 매칭 실패. 다른 표현으로 다시 요청
”데이터가 없습니다” (INFO-200)	기간이나 항목이 없는 경우. 기간을 넓히거나 다른 주기로 다시 요청
조회 범위 초과	너무 긴 기간·세밀한 주기를 한 번에 요청하면 타임아웃될 수 있음. 3~5년 단위로 나눠 요청

---

주의사항#

• ⚠️ 실시간 데이터가 아닙니다. ECOS는 확정 통계입니다. 분기 GDP는 약 2개월 뒤, 월별 CPI는 다음 달에 공표되는 등 공표 지연이 있습니다.
• ⚠️ 한국은행 공식 통계 범위만 커버합니다. ECOS에 등록된 통계표만 조회할 수 있습니다. 해당 기관에 없는 지표는 조회되지 않습니다.