datagokr — 공공데이터포털 검색을 더 쉽게 (find data.go.kr datasets easily)

datagokr

用自然语言让 AI 帮你查找并申请公共数据。

通过与 AI 对话，查找公共数据门户（data.go.kr）上的 10.9 万条数据，并让 AI 使用你的账号处理从申请使用到下载的整个流程。这项 AI 扩展功能（MCP）支持在 Claude、ChatGPT 等任意应用中搜索；申请使用和下载则需要在 Claude 桌面版等运行于你电脑上的应用中进行。介绍页面：https://datagokr.dev · 更新记录：CHANGELOG

首先需要在你的 AI 应用中安装（连接）才能使用。 如果使用 Claude 桌面版，只需下载安装文件（datagokr.mcpb）并双击即可。其他应用请参阅按使用环境查看安装和使用方法。

为什么要开发它？

直接在公共数据门户中查找数据集时，会遇到两个障碍。

• 搜索结果动辄数百条。 同一主题的数据由不同机构分别发布，因此会出现大量标题相似的数据集。
• 仅看列表无法知道有哪些列。 只有逐个打开，才能确认是否真的包含所需内容。

因此，我们已为整个门户的数据集建立索引并生成嵌入，覆盖到列（表格中的列名）。只要用自然语言描述所需数据，即使标题不完全匹配，也能找到含义相符的数据集；还会按主题归类相似数据，并可立即查看列和首行。

可以这样提问

问题	找到的数据	获取的内容
“查找包含纬度、经度信息的医院数据”	3075427 委托医院现状	无需密钥即可查看首行：浦项医疗院（36.035, 129.354）等，共 10 列
“显示全国停车场标准数据的首行”	15012896 全国停车场信息标准数据	无需密钥即可查看首行（34 列，共 18,883 行）+ 完整下载地址
“如何使用公寓实际交易价格 API？”	15126469 国土交通部开放 API	提供调用模板（端点、serviceKey）和申请使用方法说明

以上是 2026-09-27 的实际调用结果。搜索、查看结构和预览首行均无需认证密钥。

可以完成的事情分为两个阶段

第 1 阶段 · 查找和查看结构——无需安装或注册，即可立即使用

• 对话搜索：“有首尔公共停车场位置数据吗？”——即使关键词不准确，只要意思相符也能找到
• 按列搜索：“同时包含纬度、经度和医院名称的数据”
• 结构预览：查看包含哪些列，以及前几行的内容
• 获取方式说明：告知你在哪里以及如何获取数据

此阶段由公开的远程服务（https://datagokr.dev/mcp）处理。无需密钥，也无需登录。

第 2 阶段 · 申请使用和获取数据——需要在自己的电脑上安装程序（Claude 网页版和 ChatGPT 不支持）

• 一句话申请使用。 在门户上，你必须逐个打开每个数据集的详情页，点击申请按钮、选择用途、填写说明并同意条款。使用本工具时，只需说一句“帮我申请使用这些数据”，即可一次性申请最多 50 个数据集。对于自动批准的数据，可立即使用。
• 使用自己的 API 密钥直接查询。 无需阅读 API 文档，也无需在地址中附加密钥并自行调用，只要说“帮我获取几行这个 API 的数据”，就能使用自己的密钥获取数据。
• 用自然语言下载文件。 无需逐个点击每个数据集和每个历史版本的下载按钮；只要说“把这个数据全部下载下来”，就能一次性下载到包含历史版本在内的所有数据，并同时生成可在 Excel 中正常显示韩文的 UTF-8 文件。

第 2 阶段需要使用你自己的 data.go.kr 账号和 API 密钥。为了避免账号和密钥经过他人的服务器（包括我们的服务器），由在你电脑上直接连接门户的程序（此软件包）代为处理。

我的应用支持哪些功能？

使用的应用	第 1 阶段：查找	第 2 阶段：申请、下载	安装
Claude 桌面版（Windows、Mac）	✅	✅	双击安装文件
Claude 网页版（claude.ai）· ChatGPT（网页版、应用）	✅	❌ 需直接在 data.go.kr 操作	连接 Connector 地址
终端 AI（Claude Code、Codex、Cursor 等）	✅	✅ 安装此软件包后即可	注册 MCP + pip install datagokr-mcp

各环境的安装与使用方法

• Claude 桌面版（推荐，适用于第 1、2 阶段）：下载 datagokr.mcpb → 双击 → 安装。若只进行搜索，请将 3 个输入框（API 密钥、门户网站 ID、密码）留空。API 密钥是登录 data.go.kr → 我的页面 →“个人 API 认证密钥”栏中的**复制认证密钥（Decoding）**值。申请使用权限时，在对话中输入“请登录公共数据门户”（输入验证码字符）→“请为我申请使用这项数据”。了解详情
• Claude 网页版、ChatGPT（仅第 1 阶段）：只需在连接器中输入 https://datagokr.dev/mcp 地址即可。无需通过登录窗口连接。了解详情
• 终端 AI（面向开发者）：claude mcp add --transport http datagokr https://datagokr.dev/mcp，第 2 阶段使用 pip install datagokr-mcp。或者将下面这行文字粘贴给 Agent：Fetch and execute the setup instructions from https://datagokr.dev/agent-setup/prompt.md。

---

以下是面向开发者的详细文档。

第 2 阶段程序（本软件包）在我的电脑上执行的操作

只需注册公开的远程 MCP 服务（https://datagokr.dev/mcp），即可完成搜索、结构检查和首行预览，无需安装任何内容。下载完整文件、申请使用权限、使用本人密钥查询 Open API都需要用户自己的 data.go.kr 账号和密钥。为了避免密钥和登录信息经过他人的服务器（包括远程 MCP 服务），我们提供了一个可在用户电脑上直接连接门户网站的小程序。这就是本软件包。

执行的操作	运行位置	传输内容
搜索、结构、列搜索	远程 MCP 服务	仅传输搜索词、数据集 id。不含密钥和 Cookie
预览 preview	远程 MCP 服务	仅传输查询参数。不含密钥和 Cookie
下载、申请使用权限、使用本人密钥查询	用户电脑	直接连接 data.go.kr/odcloud。密钥和 Cookie 仅传输到官方服务
接收的文件	用户电脑	保存到 ~/datagokr/<dataset_id>/

本程序不会常驻后台，仅在运行 CLI 命令或 AI 客户端通过 MCP 调用时启动。代码采用 MIT 开源许可，可供完整查阅；传输范围的准确清单请参阅下文的安全与数据传输。

安装与首次查询

需要 Python 3.11 或更高版本以及互联网连接。以下命令以 macOS/Linux 的 Bash 为准。代码仓库地址为 https://github.com/datagokr-dev/datagokr，PyPI 包名为 datagokr-mcp（import 名称和 CLI 仍为 datagokr），可使用 pip install datagokr-mcp 安装；也可使用 pip install git+https://github.com/datagokr-dev/datagokr 获取最新源码。

git clone https://github.com/datagokr-dev/datagokr
cd datagokr
python3 -m venv .venv
source .venv/bin/activate
python -m pip install -e .
datagokr --version
datagokr search "전국 주차장"
datagokr show 15012896
datagokr get 15012896

搜索词仅为示例。上面的 15012896 是全国停车场信息标准数据。get 无需密钥和登录即可返回前 5 行。搜索排名、总行数和行内容会随门户网站更新而变化。也可以使用 python -m datagokr 代替 CLI 可执行文件。

如需保存完整原始数据，请运行以下命令。该命令会将完整标准数据保存为 CSV，而非仅保存前 5 行，因此可能需要更长时间。

datagokr download 15012896 --out ./downloads

响应中的 path 是实际保存路径。默认保存位置为 ~/datagokr/<dataset_id>/，指定 --out 后则保存到该目录。同一路径下的文件会被覆盖。

让 AI Agent 用一行命令安装

无论是 Claude Code、Codex、Cursor 还是其他 Agent，只需原样发送下面这句话，即可检测客户端、注册远程服务，并通过一次搜索完成验证。

Fetch and execute the setup instructions from https://datagokr.dev/agent-setup/prompt.md

配置

优先级为函数或 CLI 参数 > 环境变量 > 当前工作目录中的 .env > ~/.config/datagokr/config.toml > 默认值。None 会继承低优先级设置；空 API 密钥字符串则会停用密钥。TOML 和 .env 均使用以下大写名称。

配置键	用途	默认值
DATAGOKR_API_KEY	本人的 odcloud serviceKey，解码后的值	空值
DATAGOKR_REMOTE_URL	远程搜索、元数据、预览 MCP 地址	https://datagokr.dev/mcp
DATAGOKR_DOWNLOAD_DIR	默认下载文件夹	~/datagokr
DATAGOKR_SESSION_FILE	门户网站登录会话文件	~/.config/datagokr/session.json

如需供多个 AI 客户端共用，配置在 ~/.config/datagokr/config.toml 中会更简单。请将以下内容放在 TOML 文件的顶层。需要密钥时，请将空字符串替换为本人的密钥，并限制文件权限。

DATAGOKR_API_KEY = ""
DATAGOKR_REMOTE_URL = "https://datagokr.dev/mcp"
DATAGOKR_DOWNLOAD_DIR = "~/datagokr"
DATAGOKR_SESSION_FILE = "~/.config/datagokr/session.json"

chmod 600 ~/.config/datagokr/config.toml
datagokr config
datagokr config --json

config只会读取有效配置，不会修改文件。如果已设置密钥，将显示 [configured]，而非实际值。.env 中使用相同的 4 个名称，格式为 名称=值。不支持执行 Shell 命令或 ${变量} 替换。AI 客户端的 MCP 工作目录可能各不相同，因此若要依赖项目 .env，需要确认运行位置。

也可以仅运行一次而不使用密钥，或更改输出路径。

DATAGOKR_API_KEY='' datagokr get 15012896
DATAGOKR_DOWNLOAD_DIR=./downloads datagokr download 15012896

포털 로그인과 활용신청

검색·표준데이터 조회에는 로그인이 필요 없다. odcloud 활용신청에는 본인의 공공데이터포털 계정 세션이 필요하며 API 키와 로그인 쿠키는 서로 다른 인증정보다.

1. datagokr login을 실행하면 절차 안내가 나온다. 이 명령만으로 브라우저를 열거나 로그인하지 않는다.
2. 포털 활용신청 현황을 브라우저에서 열고 로그인한다. 보안문자는 직접 입력한다.
3. 로그인 후 www.data.go.kr 페이지에서 브라우저 쿠키를 가져온다. 다음 세 방법 중 하나를 사용한다.

브라우저 쿠키 읽기를 사용하려면 현재 소스 디렉터리에서 선택 의존성을 설치한다.

python -m pip install -e '.[browser]'
datagokr login --browser chrome
# 같은 방식으로 --browser safari 또는 --browser firefox

브라우저·운영체제의 쿠키 암호화나 권한 때문에 읽기가 실패할 수 있다. 직접 입력하려면 개발자도구 콘솔에서 document.cookie를 평가해 복사한다. 값을 생략한 datagokr login --cookie는 숨김 입력으로 받는다(권장). --cookie "값"처럼 명령줄에 직접 넣으면 셸 기록과 프로세스 인자에 남는다.

python - <<'PY'
from getpass import getpass
from datagokr.session import login

result = login(cookie=getpass("포털 쿠키: "))
print(result["message"])
PY

계정 페이지에서 로그인을 확인한 뒤 세션을 저장한다. macOS/Linux에서는 세션 파일 권한이 0600이고, Windows에서는 쿠키를 Credential Manager에 저장하고 파일에는 저장 위치 표시만 남긴다. document.cookie로는 HttpOnly 쿠키를 읽을 수 없으므로 복사한 값으로 검증이 실패하면 브라우저 쿠키 읽기 경로를 사용하거나 다시 로그인한다. 만료된 세션은 CLI의 datagokr login 또는 MCP의 login으로 갱신한다. MCP에서는 login_status 툴로 상태를 확인할 수 있다.

로컬 MCP에서는 터미널 없이 login 도구로 로그인할 수 있다. 확장 설정의 포털 아이디·비밀번호를 입력하거나 로컬 서버에 DATAGOKR_PORTAL_ID, DATAGOKR_PORTAL_PASSWORD 환경변수를 전달한다. 이 두 설정은 환경변수 전용이며 config 출력이나 개인 TOML에 넣지 않는다. 대화에 “공공데이터포털에 로그인해줘”라고 말하고, 표시된 보안문자를 직접 읽어 입력한다. 도구는 같은 challenge_id와 captcha_answer로 5분 안에 완료하며, 다시 시작하면 이전 이미지는 무효다. 아이디·비밀번호는 도구 인자에 넣지 않는다. 실제 포털 로그인과 Windows/macOS 앱 실행은 아직 실기 검증 전이다.

키가 필요한 포털 파일을 검색하고 show의 상세 페이지·요청 예시를 확인한 다음, 검색 결과의 id로 신청·조회한다. 아래 셸 변수에는 실제 검색 결과의 id를 입력한다.

read -r -p '포털 파일 dataset id: ' dataset_id
datagokr show "$dataset_id"
datagokr apply "$dataset_id" --purpose "공공데이터 통계 분석"
datagokr fetch "$dataset_id" -n 5
datagokr get "$dataset_id" -n 5

apply는 저장된 세션으로 실제 신청을 제출한다(한 번에 1~50개 id). applied나 portal_status를 확인하자. 이미 신청했거나 자동 신청 대상이 아니면 not_applicable, 로그인이 필요하면 manual 등이 반환된다. 일반 오픈API는 상세 페이지에서 별도 신청이 필요할 수 있다. 승인 직후에도 키 반영이 늦어 401이 계속되면 잠시 후 재시도하거나 get의 원문 경로를 이용한다.

CLI와 데이터 접근 방식

--json은 명령 앞이나 뒤에 붙일 수 있다. 성공 결과는 stdout, 실패 안내는 stderr에 출력하며 CLI 요청 실패는 종료 코드 1, 잘못된 인자는 2다. 성공적으로 전달된 응답 안에 status_code=401이나 신청 상태가 있을 수 있으므로 자동화에서는 응답 내용도 확인한다.

명령	예시	동작
search	datagokr search "전국 주차장" -n 5 --json	주제 검색; --dtype FILE|API|STD, --org, 반복 가능한 --field
show	datagokr show 15012896	컬럼·접근 방식·요청 예시 조회
fields	datagokr fields 위도 경도 -n 5	지정 컬럼을 모두 가진 데이터 검색
preview	datagokr preview 15012896 -n 3	키 없이 원격 서버에서 미리보기
fetch	datagokr fetch "$dataset_id" -n 5	본인 로컬 키로 odcloud 조회; --version 선택 가능
get	datagokr get 15012896 -n 3	접근 방식별 조회·신청·원문 폴백
apply	datagokr apply "$dataset_id"	본인 세션으로 활용신청 제출
download	datagokr download 15012896 --out ./downloads	원문을 로컬 디스크에 저장
login	datagokr login	로그인 안내 또는 쿠키 등록
config	datagokr config --json	키를 가린 유효 설정 조회

각 명령의 전체 옵션은 datagokr <명령> --help로 확인한다. 검색·컬럼 검색은 원격 서버에서 최대 20건, 원격 미리보기는 최대 20행·50컬럼이다. show도 컬럼을 최대 50개 표시한다.

access_kind	get의 결과
STD_FILE	무키로 표준데이터 첫 n행. 파일이 없는 API 전용 표준은 요청 템플릿 안내
STD	전국판 부모가 있으면 그 본문과 부모 id 반환; 없으면 카탈로그 안내
LINK	제공기관의 외부 URL
OPEN_API	본인 serviceKey로 호출할 요청 템플릿 또는 포털 상세 페이지
PORTAL_FILE	키로 odcloud 조회 → 401이면 로그인 세션으로 신청 → 승인 확인 후 재조회 → 원문 미리보기·다운로드 폴백. 키가 없으면 바로 원문 경로

get은 기본적으로 활용신청을 하지 않고 원문 파일 저장으로 폴백한다. 본인 계정으로 신청까지 하려면 get --apply를 명시한다(MCP·Python API는 no_apply=False). get --probe는 신청·파일 저장 없이 접근을 확인한다. download --probe도 저장하지 않는다. 포털 원문 미리보기는 CSV/TSV/TXT/XLSX를 지원하고, 지원하지 않는 형식이나 미리보기 실패는 원문 다운로드로 이어질 수 있다.

포털 파일은 download --version 버전키 또는 download --all-versions로 버전을 선택한다(동시 사용 불가). show의 요청 예시를 참고한다. --utf8은 CSV 원문과 함께 UTF-8 변환본을 추가 저장한다. 표준데이터 CSV는 기본적으로 UTF-8 BOM 인코딩이다.

在 AI 客户端中注册 MCP

本地 datagokr-mcp 通过 stdio 运行，并提供 10 个工具：search、show、fields、preview、fetch、get、apply、download、login、login_status。工具说明同时提供韩语和英语。CLI 的 login 和 config 也保留；MCP 不接受密钥、ID、密码或 Cookie 作为输入参数。

首先，在已安装的虚拟环境中运行 command -v datagokr-mcp，确认可执行文件的绝对路径。下面的示例要求 AI 客户端的 PATH 中也能找到 datagokr-mcp。如果找不到，请将每个 command 或 CLI 命令末尾的可执行文件替换为刚确认的绝对路径。不要指望 JSON/TOML 的命令路径会展开 ~。也可以将 command 设为虚拟环境 Python 的绝对路径，并将 args 指定为 ["-m", "datagokr.mcp"]。

合并各项设置时，请保留现有文件中的其他项目。将密钥放在个人的 ~/.config/datagokr/config.toml 中，就无需在下面的示例中填入机密值。注册后，在客户端中刷新 MCP 连接或重启客户端。

Claude 网页版·ChatGPT（连接器，仅限第 1 阶段）

这些应用无法运行本地程序，因此只能通过连接器连接远程服务（Claude 桌面应用建议使用下方的扩展文件）。在 Claude 中，前往“设置”→“连接器”→“添加”→“自定义连接器”，名称任意，URL 填入 https://datagokr.dev/mcp（包括末尾的 /mcp），然后连接。高级设置中的 OAuth 客户端 ID 和密钥留空。连接过程中会自动完成授权，无需登录页面。在 ChatGPT（网页版·应用版）中，前往“设置”→“集成”→“插件”→“添加”→“创建 MCP 应用”，填入相同的 URL，并将身份验证设为 OAuth（菜单名称可能因版本和套餐而异）。可以进行搜索、查看结构和预览（第 1 阶段），但不能申请使用、查询个人密钥或下载全部数据（第 2 阶段）。如有需要，请直接前往 AI 提供的 data.go.kr 页面操作。

Claude 桌面应用（Windows·Mac）

第 1、2 阶段均可使用。只需一个文件，即可在此电脑上安装搜索、查询、申请使用和下载工具。需要使用最新版本的 Claude 桌面应用并连接互联网。

1. 从 Releases 下载 datagokr.mcpb。也可以直接下载扩展文件。
2. 双击下载的文件，并在 Claude 桌面应用中安装。应用会准备 Python 和所需的软件包。
3. 在设置窗口中输入你的 API 密钥、门户 ID 和密码。这些信息均为可选项；如果想先进行搜索，也可以留空。API 密钥是在 data.go.kr 登录后，前往“我的页面”首页，在“个人 API 认证密钥”栏中点击**复制认证密钥（Decoding）**后得到的值（菜单：我的页面 → 数据利用 → Open API → 认证密钥签发现况）。
4. 在新对话中输入“搜索全国停车场数据”。如果需要登录门户，请输入“登录公共数据门户”，然后亲自阅读并输入显示的验证码。不要在对话中输入密码。
5. 确认所需数据集后，在对话中请求申请使用或下载。收到的文件会保存在此电脑的 ~/datagokr/<dataset_id>/ 中。

API 密钥和登录信息会从用户电脑直接发送至官方服务。已在 Linux VPS 上确认捆绑启动和工具列表；Windows/macOS 应用安装以及实际门户登录尚未进行实机验证。

也可以继续手动注册。将已安装的可执行文件作为 "datagokr-local": {"command": "/absolute/path/to/.venv/bin/datagokr-mcp"} 添加到 claude_desktop_config.json 的 mcpServers 中。如果已通过扩展安装，则无需重复注册同一个本地服务。

Claude Code

claude mcp add datagokr-local -s user -- /absolute/path/to/.venv/bin/datagokr-mcp
claude mcp add --transport http datagokr-public https://datagokr.dev/mcp -s user
claude mcp list

本地服务在用户电脑上运行；远程服务连接到用于搜索和查询的公开服务。只需注册所需的连接。-s user 适用于所有项目；可通过 claude mcp list 或对话框中的 /mcp 检查连接。删除连接的命令为 claude mcp remove datagokr-local -s user 和 claude mcp remove datagokr-public -s user。Claude Code 官方 MCP 文档。

Codex CLI

通过 CLI 注册所需的连接。

codex mcp add datagokr-local -- /absolute/path/to/.venv/bin/datagokr-mcp
codex mcp add datagokr-public --url https://datagokr.dev/mcp
codex mcp list
codex exec --skip-git-repo-check "datagokr-public 서버의 search 툴로 '전국 주차장' 1건만 검색해서 제목만 답해"

list 中的 enabled 表示已注册。实际连接和调用是否成功，请通过对话中的工具响应确认。删除连接的命令为 codex mcp remove datagokr-local 和 codex mcp remove datagokr-public。如需直接设置，请将配置添加到 ~/.codex/config.toml，而不要通过 CLI 注册。

[mcp_servers.datagokr-local]
command = "datagokr-mcp"
startup_timeout_sec = 30
tool_timeout_sec = 180

通过 codex mcp list 或 /mcp 检查。如果通过环境变量管理密钥，可以在上方的表格中添加 env_vars = ["DATAGOKR_API_KEY"] 以传递密钥。OpenAI 官方 MCP 文档。

Cursor

将配置添加到项目的 .cursor/mcp.json 中。如需在所有项目中使用，请使用 ~/.cursor/mcp.json。

{
  "mcpServers": {
    "datagokr": {
      "command": "datagokr-mcp",
      "args": []
    }
  }
}

Cursor 官方 MCP 文档。

Gemini CLI

将配置添加到 ~/.gemini/settings.json 中。

{
  "mcpServers": {
    "datagokr": {
      "command": "datagokr-mcp",
      "args": [],
      "timeout": 180000
    }
  }
}

通过 /mcp 检查连接。timeout 的单位是毫秒。Gemini CLI 官方 MCP 文档。

Windsurf

将配置添加到 ~/.codeium/windsurf/mcp_config.json 中。

{
  "mcpServers": {
    "datagokr": {
      "command": "datagokr-mcp",
      "args": []
    }
  }
}

在 Cascade 的 MCP 设置中检查服务和工具。Windsurf 官方 MCP 文档。

其他客户端只要支持本地 stdio MCP，也可以通过相同的命令连接。datagokr-mcp 是由 MCP 客户端启动的进程，因此直接在终端运行时，即使没有输出，也可能是在等待输入。可以在对话中提出“搜索全国停车场数据，并显示 15012896 的前 3 行”之类的请求。大型下载可能会超过客户端的超时时间，因此也可以通过 CLI 执行。

Python API

import datagokr

search = datagokr.search("전국 주차장", n=5)
print(search["summary"])
datasets = search["results"]
details = datagokr.show("15012896")
result = datagokr.get("15012896", n=3, api_key="")
print(result["data"]["columns"])
print(result["data"]["rows"])
files = datagokr.download("15012896", out="./downloads")

search와 fields는 {"summary": {...}, "results": [...]} dict를 반환한다. 같은 주제의 지자체 자료는 대표 한 줄로 접힌다. 다음은 필드 의미를 보여 주는 축약 예시이며 건수·순위는 실제 검색에 따라 달라진다.

{
  "summary": {
    "total_groups": 1,
    "total_datasets": 2,
    "by_dtype": {"FILE": 2},
    "by_access_kind": {"PORTAL_FILE": 2},
    "by_org_level": {"national": 0, "local": 2},
    "region_hint": null,
    "dtype_hint": null,
    "note": "지자체별로 나뉜 주제를 접었습니다. group_ids의 id를 show로 펼쳐 보세요."
  },
  "results": [{
    "id": "<대표 id>",
    "title": "부산광역시 북구_재난문자 발송 현황",
    "group_count": 2,
    "group_ids": ["<대표 id>", "<다른 지자체 id>"],
    "group_orgs": ["부산광역시 북구", "제주특별자치도"],
    "group_kinds": {"PORTAL_FILE": 2},
    "desc_short": "재난문자 발송 현황입니다.",
    "top_columns": ["발송일시", "내용"],
    "portal_updated": "2026-09-10",
    "org_level": "local"
  }]
}

summary는 n개로 자르기 전 검색 후보의 개요이며 전체 카탈로그 건수가 아니다. group_count는 대표를 포함한 후보 멤버 수, group_ids는 순위순 최대 60개 id다. 각 id를 datagokr.show(dataset_id)에 넣어 펼쳐 본다. desc_short는 설명 앞 120자에서 개행을 뺀 값, top_columns는 등록순 컬럼명 최대 5개, portal_updated는 ISO 날짜 또는 null, org_level은 national 또는 local이다. 지역·API/파일 의도는 서버가 추출하지만 dtype·org 인자를 주면 더 정확하다.

최상위 공개 함수는 search, show, fields, preview, fetch, get, apply, download다. fields에는 컬럼명 리스트, apply에는 id 리스트를 전달한다. 원격 주소는 remote_url=, 키를 사용하는 함수에는 api_key=로 설정을 덮어쓸 수 있다. get의 no_apply(기본 True, 신청 안 함)·probe=True와 download의 probe=True는 CLI와 같은 의미다. 반환값은 dict 또는 list이고 Python API는 동기 호출이다.

보안과 데이터 전송

원격 서버로 전송되는 것 / 안 되는 것

작업	원격 MCP 서버로 전송되는 것	원격 MCP 서버로 전송되지 않는 것
search·show·fields·record·download_url	질의·필드 조건·식별자·건수 등 조회 인자만	API 키·로그인 쿠키·로컬 파일
preview (원격 get_preview)	조회 인자만	API 키·로그인 정보·쿠키·로컬 파일
get·fetch·apply·download	record로 카탈로그 식별자 조회만	키·쿠키·신청 본문: 사용자 컴퓨터에서 포털/odcloud로 직접 전송; 파일은 로컬 저장

record·download_url은 원격 툴이며 최상위 Python API나 CLI 명령은 아니다. 로그인 쿠키는 어떤 경우에도 원격 MCP 서버로 보내지 않는다. AI 클라이언트에 반환한 데이터의 처리는 해당 클라이언트의 정책을 따른다.

• 검색어·필드 조건·데이터셋 id는 설정한 원격 MCP 서버로 전달된다. 서버는 검색·메타·원격 미리보기를 제공하며 원격 서버 자체는 활용신청이나 사용자 파일 저장을 하지 않는다.
• preview는 초기화·툴 목록 요청을 포함해 API 키를 보내지 않는다. 기존 api_key=·--api-key 인자는 호환성을 위해 받지만 미리보기에서는 사용하지 않는다. 키가 필요한 조회는 로컬 get/fetch를 사용한다.
• get/fetch의 API 키는 로컬에서 odcloud로 전달된다. 포털 로그인 쿠키는 사용자 세션 파일에 저장하고 포털 접속에 사용하며 원격 검색 MCP에는 보내지 않는다. 다운로드는 MCP 서버 프로세스가 실행되는 컴퓨터에 저장된다.
• CLI/MCP는 키·쿠키를 출력하거나 오류 메시지에 포함하지 않도록 처리한다. 하지만 사용자가 직접 인쇄하거나 HTTP 디버그 로깅을 켜거나 명령줄 인자에 비밀값을 넣으면 노출될 수 있다. 키·쿠키를 AI 대화, 버그 보고, 커밋에 붙여 넣지 않는다.
• 포털 로그인 아이디·비밀번호는 이 컴퓨터에서 auth.data.go.kr로 직접 전송한다. 로그인 이동은 auth.data.go.kr·www.data.go.kr의 HTTPS만 허용하고, 포털 계정 페이지와 저장할 쿠키의 재사용을 확인한 뒤 성공을 반환한다. 보안문자 이미지는 AI 클라이언트에 표시하므로 사용자가 직접 읽어 입력한다.
• 세션은 macOS/Linux에서 0600 파일, Windows에서 Credential Manager에 저장한다. .env·개인 설정 파일도 접근 권한을 제한하고 버전 관리에서 제외한다. 원격 주소를 변경하면 그 서버가 검색 입력을 받으므로 신뢰하는 HTTPS 주소를 사용한다.
• get은 기본적으로 자동 활용신청을 하지 않으며 파일 저장으로 폴백할 수 있다. get --apply로 신청을 허용할 수 있고, apply는 신청 제출, download는 파일 저장을 수행한다. get/download는 같은 파일을 덮어쓸 수 있다. 조회만 원하면 probe 옵션을 사용한다.

데이터 출처와 이용조건

데이터 출처는 공공데이터포털(data.go.kr)과 각 제공기관이다. 데이터셋별 이용허락(공공누리 유형, 출처표시 등)은 검색 결과의 page_url에 표시된 조건을 따른다. 이 패키지와 원격 서버는 카탈로그 색인과 접근 안내를 제공하며, 미리보기·조회·다운로드로 받은 데이터의 별도 이용권을 부여하지 않는다. 패키지의 MIT 라이선스는 코드에 적용되고 데이터셋의 이용조건을 대체하지 않는다.

레이트리밋

공개 원격 서버는 툴 호출(tools/call)을 IP당 최근 60초 30회, UTC 날짜당 2,000회까지 허용한다. 전체 IP 합계 제한(최근 60초 120회·최근 24시간 10,000회)도 적용된다. 초기화·툴 목록·ping 같은 나머지 요청은 IP당 최근 60초 120회·날짜당 10,000회로 따로 센다. /health는 제외된다. HTTP 429를 받으면 Retry-After만큼 기다린다. 패키지는 이를 읽어 한 번 재시도한다. 자체 호스팅 서버의 한도는 운영 설정에 따라 달라질 수 있다.

문제 신고

오류·문서 수정·서비스 문의는 GitHub Issues에 남긴다. 패키지 버전과 재현 명령, 비밀값을 제거한 오류를 함께 적고 API 키·로그인 쿠키·개인 설정 파일은 첨부하지 않는다.

검증과 문제 해결

개발 테스트는 HTTP mock과 실제 stdio 프로세스를 사용한다. 기본 실행에서는 외부 네트워크 테스트 한 개를 건너뛴다. 모든 테스트 출력에 [TEST]를 붙이는 실행 예시는 다음과 같다.

python -m pip install -e '.[dev]'
set -o pipefail
python -m pytest -q 2>&1 | sed 's/^/[TEST] /'
DATAGOKR_LIVE_TEST=1 python -m pytest -q -s 2>&1 | sed 's/^/[TEST] /'

실서버 테스트는 기본 공개 서버와 포털에 접속해 무키 CLI 검색·get 15012896·MCP stdio 목록/검색을 검증한다. 다운로드·로그인 세션 경로는 임시 디렉터리로 지정한다. 최초 health 연결 자체가 불가능하면 skip하고, 연결 후 잘못된 응답·데이터·툴 계약은 실패로 처리한다. 실제 환경 점검에서는 skip을 성공으로 간주하지 말자.

증상	확인할 것
datagokr-mcp 실행파일을 못 찾음	설치한 가상환경의 절대경로를 MCP 설정에 지정
검색·메타 조회 실패	인터넷·DATAGOKR_REMOTE_URL 확인, 잠시 후 재시도; 429는 Retry-After만큼 기다려 한 번 재시도
fetch의 401 또는 키 관련 안내	본인의 디코딩 키·활용신청·승인 반영 상태 확인; 무키 조회는 get
로그인 실패·만료	datagokr login의 절차로 재로그인; 브라우저 선택 의존성·쿠키 읽기 권한 확인
get이 행 대신 URL·템플릿·파일 경로 반환	access_kind에 따른 정상 경로; 반환된 안내와 파일 확인
원문이 없거나 빈 파일 안내	포털 상세 페이지와 제공기관 링크 확인; 모든 카탈로그 항목이 다운로드 가능한 파일인 것은 아님