aikstockdata

# aikstockdata — 한국 주식 공시·시세를 AI가 바로 읽는 무료 JSON + MCP 서버

**KOSPI·KOSDAQ·KONEX 전 종목의 확정 종가와 KOSPI·KOSDAQ 지수, DART 공시, 종목당 1년치 일별 시세를
매 거래일 저녁 AI가 읽을 수 있는 JSON으로 발행합니다.
가입도, API 키도, 요청 제한도 없습니다.**

<sub>수록 종목 수는 매 거래일 바뀝니다 — 여기에 수를 적어 두면 그 순간부터 낡습니다.
현재 값은 [`index.json`](https://aikstockdata.com/data/public/index.json) 의 `coverage`
(`universe_n` · `published_n` · `excluded_n`)에 있습니다.</sub>

🔗 **사이트** https://aikstockdata.com · **MCP 주소** `https://mcp.aikstockdata.com/mcp`

[공식 MCP 레지스트리](https://registry.modelcontextprotocol.io/v0.1/servers?search=com.aikstockdata/mcp)에
**`com.aikstockdata/mcp`** 로 등재돼 있습니다(도메인 확인 완료).

[![Hugging Face](https://img.shields.io/badge/%F0%9F%A4%97%20dataset-korea--equity--daily-yellow)](https://huggingface.co/datasets/aikstockdata/korea-equity-daily)
[![Kaggle](https://img.shields.io/badge/Kaggle-dataset-20BEFF)](https://www.kaggle.com/datasets/aikstokdata/korean-equity-daily-prices-dart-filing-impact)
[![MCP](https://img.shields.io/badge/MCP-server-blue)](https://modelcontextprotocol.io)
[![Auth](https://img.shields.io/badge/auth-none-brightgreen)]()
[![License](https://img.shields.io/badge/data-public%20domain%20derived-brightgreen)]()

> English documentation is in the [second half of this page](#english).

---

## 30초 만에 AI에 붙이기

### Claude · ChatGPT — MCP 커넥터

설정의 **커스텀 커넥터**에 아래 주소를 붙여넣으면 끝입니다. 인증이 없습니다.

```
https://mcp.aikstockdata.com/mcp
```

**Claude Code** 는 한 줄입니다.

```bash
claude mcp add --transport http aikstockdata https://mcp.aikstockdata.com/mcp
```

설정 파일을 직접 쓰는 도구라면(`claude_desktop_config.json` 등):

```json
{
  "mcpServers": {
    "aikstockdata": {
      "type": "http",
      "url": "https://mcp.aikstockdata.com/mcp"
    }
  }
}
```

도구 12개가 생깁니다.

| 도구 | 무엇을 |
|---|---|
| `get_today` | 오늘 시장 한 방에 — 등락·상승하락 종목 수·주요 공시 |
| `search_stock` · `get_stock` | 종목 찾기 · 종목 상세(시세·재무·공시) |
| `get_rankings` · `get_market_summary` | 순위표 · 시장 요약 |
| `get_disclosures` | **무슨 공시가 몇 시에 났나** — 접수 시각(HH:MM)과 장 구분(장전·장중·장마감후). 공개 API 어디에도 없는 값입니다 |
| `list_stocks` | **조건에 맞는 종목 목록** — 흑자전환·52주 신고저에 시총÷연환산영업이익 배수 상한까지 |
| `get_earnings` | **잠정 실적 포함** — 정기보고서보다 2주 빠릅니다 |
| `get_earnings_calendar` | **누가 냈고 누가 아직인가** — 법정 마감 D-day, 직전 발행 대비 신규 목록. 상태를 못 들고 다니는 에이전트에겐 이게 웹훅을 대신합니다 |
| `get_history` | 250거래일 일별 시세 + 52주 고저·고점 대비 낙폭·거래량 배수 |
| `get_disclosure_impact` | 공시 유형별로 그 뒤 1·5거래일 주가(시장 등락을 뺀 값). 20거래일은 그 유형의 표본이 차면 나옵니다 — 응답의 h20_status 를 보세요 |
| `get_data_urls` | 원자료 주소 카탈로그 — 도구에 없는 것도 JSON 으로 다 있습니다 |

그다음엔 그냥 물어보면 됩니다: *"오늘 한국 시장 어땠어?"* · *"삼성전자 최근 공시 정리해줘"* ·
*"흑자전환한 종목 중에 시총이 영업이익의 10배 안 되는 것만"*

### MCP 없이 — 주소만 붙여넣기

```
https://aikstockdata.com/data/public/today.json 을 읽고 오늘 한국 시장을 요약해줘.
```

### Python

```python
import urllib.request, json

def get(path):
    url = "https://aikstockdata.com/data/public/" + path
    # User-Agent 를 반드시 준다. CDN 봇 필터가 파이썬 기본 UA 를 403 한다.
    req = urllib.request.Request(url, headers={"User-Agent": "my-app"})
    return json.load(urllib.request.urlopen(req))

today = get("today.json")            # 오늘 하루 요약 (7KB)
samsung = get("s/005930.json")       # 한 종목 (5KB)
hist = get("s/005930_history.json")  # 1년치 [날짜, 종가, 거래량] (7KB)
```

> ★**종목코드는 여섯 자리 문자열입니다.** 정수로 읽으면 `000020`이 `20`이 됩니다.
> pandas 를 쓴다면 `dtype={"code": str}` 를 반드시 주세요.

### curl

```bash
curl -s https://aikstockdata.com/data/public/s/005930.json
```

---

## 이렇게 물어보세요

MCP 를 붙였거나 주소를 붙여넣었다면, 아래는 **그대로 복사해 쓰는 질문**입니다.
전부 우리 데이터로 답할 수 있는 것만 골랐습니다.

### 오늘 무슨 일이 있었나

```
오늘 한국 시장 어땠어? 지수랑 오른 종목 수를 같이 알려줘.
```
> 지수와 상승 종목 수는 자주 반대를 가리킵니다. 둘 다 봐야 합니다.

```
오늘 접수된 공시 중 중요도 높은 것 10건만 쉬운 말로 풀어줘.
```

```
오늘 장 마감 후에 나온 공시만 골라줘. 아직 종가에 반영되지 않은 것들이야.
```
> 이게 우리만 답할 수 있는 질문입니다 — 공개 API 에는 접수 **날짜**만 있습니다.

### 한 종목을 파고들 때

```
삼성전자 최근 공시랑 분기 실적 정리해줘. 전년 동기 대비도.
```

```
005930 의 최근 1년 종가 흐름에서 최고가 대비 지금 몇 % 지점인지 계산해줘.
```
> `s/005930_history.json` 한 파일(7KB)로 끝납니다.

```
SK하이닉스가 최근에 낸 공시 중에 자기주식 관련된 게 있어?
```

### 여러 종목을 훑을 때

```
시가총액 상위 20개 종목의 오늘 등락률을 표로 만들어줘.
```

```
최근 120일 안에 실적을 발표한 종목 중 영업이익이 전년 대비 늘어난 곳을 찾아줘.
```

```
52주 신고가를 찍은 종목이 오늘 몇 개야?
```

### 공시가 나온 뒤에 무슨 일이 있었는지

```
배당 결정 공시 뒤 5거래일 동안 시장 대비 수익률이 어땠는지 알려줘.
신뢰구간도 같이 보여주고, 0을 포함하는지 판단해줘.
```
> **숫자만 받아 오지 말고 구간을 같이 물어보세요.** 현재 숫자가 있는 18칸 중
> 15칸의 95% 구간이 0을 포함합니다. 그 사실을 감추지 않는 것이 이 표의 요점입니다.

```
공시 접수 시각이 장 시작 전인 건과 장 마감 후인 건을 나눠서,
공시 당일 수익률 중앙값을 각각 계산해줘.
```
> 접수 시각이 없으면 이 질문 자체가 불가능합니다.

### 데이터를 검증하고 싶을 때

```
https://aikstockdata.com/data/public/index.json 을 읽고
지금 데이터가 며칠 전 것인지, 신선도 상태가 뭔지 알려줘.
```
> 신선도는 저희 주장이 아니라 계산값입니다. 오래되면 스스로 `stale` 이라고 밝힙니다.

```
disclosure_impact.json 의 per_event 를 받아서 배당 결정 유형의 +5일
중앙값을 직접 다시 계산해줘. cluster 로 중복을 먼저 제거하고.
```
> **집계를 반박하라고 개별 값을 싣습니다.** 같은 `cluster` 는 한 번만 세야 합니다
> — 안 그러면 저희가 저질렀던 중복 계산이 재현됩니다.

---

## 왜 만들었나

한국 시장 데이터는 AI가 쓰기 어렵습니다. 공식 출처(금융위원회 공공데이터포털,
금융감독원 DART)는 **API 키를 먼저 받아야 하고**, 한글 필드명이 그대로인 XML·JSON을 주며,
값이 **없는 것인지 0인 것인지 구분할 방법을 주지 않습니다.**

이 프로젝트는 그것을 LLM이 그대로 읽는 자기설명형 JSON으로 정규화하고, 주소 하나만
붙여넣으면 되는 MCP 서버를 얹었습니다.

**실질적인 차이는 자격증명입니다.** 한국 주식 MCP 서버 대부분은 DART·증권사 API를 실시간으로
중계하기 때문에 첫 호출 전에 키 발급이 필요합니다. 이 서버는 **미리 만들어 둔 공개 파일**을
내보내므로 주소를 붙여넣는 순간부터 동작합니다.

---

## 여기서만 무료로 얻는 것

### 1. ★공시 접수 시각 (HH:MM) — 공개 API 어디에도 없습니다

DART 공시검색 API가 주는 접수 정보는 **날짜(YYYYMMDD)뿐**입니다. 개별 공시 뷰어에도,
공시검색 화면에도 시:분이 없습니다. 그런데 같은 날짜의 공시라도 **장중에 나온 것**과
**장 마감 후에 나온 것**은 그날 종가에 대해 정반대를 뜻합니다 — 앞의 것은 이미 주가에
반영됐고, 뒤의 것은 아직 반영되지 않았습니다.

저희는 시:분이 남아 있는 유일한 곳에서 이 값을 따로 모아 붙입니다.

```
https://aikstockdata.com/data/public/disclosures.json          # 18:10 발행 · events[].receipt_time · session
https://aikstockdata.com/data/public/disclosures_intraday.json # 15:00 발행 · 그날 접수 전건
https://aikstockdata.com/data/public/dart_receipt_times.json   # 접수번호 ↔ 시각 대조표
```

`session` 은 정규장(09:00~15:30) 기준 세 갈래입니다.

| 값 | 뜻 | 그날 종가 움직임은 |
|---|---|---|
| `pre_open` | ~09:00 접수 | 전체가 공시 **뒤** — 반응으로 읽을 수 있는 유일한 경우 |
| `intraday` | 09:00~15:30 | 앞부분은 공시 이전 — 섞여 있습니다 |
| `after_close` | 15:30~ | 전체가 공시 **앞** — 공시 반응이 아닙니다 |

```python
d = get("disclosures.json")
late = [e for e in d["events"] if e["session"] == "after_close"]
# 오늘 장 마감 뒤에 나온 공시 — 아직 종가에 반영되지 않았다
```

실측으로 **접수 건의 40% 안팎이 장 마감 후**입니다. 시각이 없으면 그 40%를 그날 종가의
반응으로 잘못 읽게 됩니다.

### 2. 공시 유형별로 그 뒤에 실제로 무슨 일이 있었나

공시마다 그 종목의 일별 종가와 소속 지수를 붙여 두었습니다. *"이런 종류의 공시 뒤에
시장은 어떻게 움직였나"* 를 **기록으로서** 물을 수 있습니다 — 예측이 아닙니다.

```
https://aikstockdata.com/data/public/disclosure_impact.json
```

유형별로 +1 / +5거래일 뒤의 **시장조정 수익률 중앙값**(종목 수익률 − 같은 기간
소속 지수 수익률)과 시장을 이긴 비율을 함께 냅니다. +20거래일은 그 유형의 표본이
차면 유형별로 나옵니다 — 응답의 `h20_status` 를 보세요(없다고 결론내지 말 것).
개별 값은 DART 접수번호를 열쇠로 싣기 때문에 원문과 대조할 수 있습니다.

표본이 20건 미만인 유형에는 **숫자를 넣지 않습니다.** 몇 건짜리 중앙값은 우연을 통계로
둔갑시킵니다. 95% 구간도 함께 싣는데, **현재 숫자가 있는 18칸 중 17칸의 구간이 0을 포함합니다.**
그 사실을 감추지 않는 것이 이 표의 요점입니다.

### 3. 종목당 1년 시세가 한 파일 7KB

`s/{종목코드}_history.json` — 최대 250거래일의 `[날짜, 종가, 거래량]`.
행을 객체가 아니라 배열로 둡니다. 여섯 개 키 이름을 250번 반복하면 정보 없이 파일만
두 배가 됩니다(실측 14.3KB → 6.8KB).

### 4. 지수와 상승 종목 수를 따로 줍니다 — 둘이 어긋나기 때문에

`today.json` 은 KOSPI·KOSDAQ 종가와 상승·하락 종목 수를 **둘 다** 싣습니다. 이 둘은
자주 반대를 가리킵니다. 2026-08-03 에는 코스피가 5.12% 내렸는데 855종목이 오르고
518종목이 내렸습니다 — 지수는 시총 가중이고 종목 수는 한 종목 한 표이기 때문입니다.
대부분의 출처는 둘 중 하나만 주고 나머지는 같으려니 하게 만듭니다.

### 5. 거래일마다 영구 주소가 남습니다

`https://aikstockdata.com/market/{YYYY-MM-DD}` — 주소의 날짜는 발행일이 아니라
**종가 기준일**입니다. (한 번 틀린 적이 있습니다. 폭락한 날 페이지가 몇 시간 동안
+17.9% 머리기사를 달고 있었습니다. 지금은 날짜와 데이터가 어긋날 수 없습니다.)

---

## 통짜로 받고 싶다면

발행일에 고정된 스냅샷입니다. 매 거래일 갱신되는 원본은 위 주소들입니다.

| 어디 | 무엇 |
|---|---|
| [Hugging Face](https://huggingface.co/datasets/aikstockdata/korea-equity-daily) | JSON Lines · 종목 마스터 · 일별 종가 · 공시 유형별 이후 주가 |
| [Kaggle](https://www.kaggle.com/datasets/aikstokdata/korean-equity-daily-prices-dart-filing-impact) | CSV 4개 · **공시 접수 시각 열 포함** |

인용용 **월간 동결본**은 허깅페이스의 `korea-equity-daily-YYYY-MM` 에 따로 있습니다 —
한 번 올리고 다시 고치지 않으므로 이름만 적으면 됩니다(리비전 해시 불필요).
`main` 은 **갱신될 때마다 통째로 덮어쓰이는 자리**라 인용에 쓸 수 없습니다.
그 스냅샷이 언제 것인지는 데이터셋 카드 첫 줄이 날짜로 밝힙니다 —
매 거래일 갱신되는 것은 미러가 아니라 [사이트의 원본](https://aikstockdata.com/data/public/index.json)입니다.

---

## 파일로 직접 받기 — 무엇이 얼마나 큰가

MCP 없이 주소만 쓸 때 필요한 표입니다. **크기는 정확한 수가 아니라 띠**입니다 —
파일은 매 거래일 커지므로 여기 수를 박아 두면 그날 저녁부터 거짓이 됩니다.
2026-09-10 18:10 KST 기준이고, 현재 값은 언제나
[`index.json`](https://aikstockdata.com/data/public/index.json) 의 `file_bytes` 에 있습니다.

> ⚠️ **대부분의 AI fetch 도구는 응답을 150 KB 안팎에서 자릅니다. 잘린 JSON 은
> 파싱되지 않습니다.** 지금 34개 중 **12개가 그 문턱을 넘습니다** —
> 표에서 ★큼 으로 표시된 것은 소형 대체본을 쓰세요. 대체본 목록은 카탈로그의
> `fetch_guide.small_alternatives` 에 있습니다.

| 파일 | 무엇이 들었나 | 크기 |
|---|---|---|
| [`earnings.json`](https://aikstockdata.com/data/public/earnings.json) | 어닝 스코어보드(실적 공시 롤링 120일 — rankings 에서 분리) | ★큼 (~2,936 KB) — 직접 받지 말고 `earnings_recent60.json` |
| [`disclosure_impact.json`](https://aikstockdata.com/data/public/disclosure_impact.json) | 공시 유형별 이후 주가 경로(시장조정 중앙값) | ★큼 (~1,745 KB) — 직접 받지 말고 `disclosure_impact_summary.json` |
| [`quotes.json`](https://aikstockdata.com/data/public/quotes.json) | 시세 전체(T+1 종가) | ★큼 (~731 KB) — 직접 받지 말고 `quotes_top300.json` |
| [`screen.json`](https://aikstockdata.com/data/public/screen.json) | ★조건 검색 재료(전 종목 한 줄 — 흑자전환·시총/영업이익 배수·52주 신고저) | ★큼 (~584 KB) — 직접 받지 말고 `screen_top300.json` |
| [`search_index.json`](https://aikstockdata.com/data/public/search_index.json) | 종목 인덱스(전 종목 code·이름·개별 JSON URL 리터럴 — 476KB, URL 조립 못 하는 환경용) | ★큼 (~476 KB) — 직접 받지 말고 `search_index_rows.json` |
| [`earnings_calendar.json`](https://aikstockdata.com/data/public/earnings_calendar.json) | ★실적 캘린더(이번 분기 접수 완료 / 아직 없음 + 법정 마감 D-day) | ★큼 (~446 KB) — 직접 받지 말고 `earnings_calendar_summary.json` |
| [`quotes_slim.json`](https://aikstockdata.com/data/public/quotes_slim.json) | 시세 경량판(핵심 6필드 · 374KB · 잘림 문턱 초과 — 전 종목이 필요할 때) | ★큼 (~374 KB) — 직접 받지 말고 `quotes_min.json` |
| [`dart_receipt_times.json`](https://aikstockdata.com/data/public/dart_receipt_times.json) | ★DART 공시 접수 시각(HH:MM) — 공개 API 에는 날짜만 있고 시:분이 없다 | ★큼 (~340 KB) — 직접 받지 말고 `dart_receipt_times_min.json` |
| [`quotes_en.csv`](https://aikstockdata.com/data/public/quotes_en.csv) | 시세 CSV(영문 헤더) | ★큼 (~286 KB) — 도구로 직접 받지 마세요 |
| [`quotes.csv`](https://aikstockdata.com/d