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

datagokr

公共データを、AIに話しかけて探し、申請まで任せましょう。

公共データポータル（data.go.kr）の10.9万件のデータをAIと会話しながら探し、自分のアカウントで利用申請からダウンロードまで処理するAI拡張機能（MCP）です。検索はClaude・ChatGPTのどちらでもでき、利用申請・ダウンロードはClaudeデスクトップのように自分のコンピューター上で動作するアプリで行えます。紹介ページ：https://datagokr.dev · 更新履歴：CHANGELOG

まずは自分のAIアプリにインストール（接続）する必要があります。 Claudeデスクトップならインストールファイル（datagokr.mcpb）をダウンロードしてダブルクリックするだけです。他のアプリについては環境別のインストール・使用方法をご覧ください。

なぜ作ったのですか？

公共データポータルでデータセットを直接探していると、2つの壁にぶつかります。

• 検索結果が数百件も表示されます。 同じテーマのデータを機関ごとに別々に登録しているため、似たようなタイトルのデータセットがたくさん見つかります。
• 一覧だけでは、どの列があるのかわかりません。 探している内容が本当に含まれているかは、一つずつ開いて確認する必要があります。

そこで、ポータル全体を列（表の列名）まで事前にインデックス化して埋め込みました。必要なデータを言葉で説明すれば、タイトルが完全に一致していなくても意味の合うデータセットを見つけ、似たものをテーマ別にまとめて表示し、列や先頭行までその場で確認できます。

こんなふうに質問できます

質問	見つかったデータ	得られるもの
「緯度・経度情報がある病院データを探して」	3075427 委託病院の現況	キーなしで先頭行を確認：浦項医療院（36.035, 129.354）など10列
「全国駐車場標準データの先頭行を見せて」	15012896 全国駐車場情報標準データ	キーなしで先頭行（34列、全18,883行）＋全件ダウンロード先
「マンションの実取引価格APIの使い方は？」	15126469 国土交通部オープンAPI	呼び出しテンプレート（エンドポイント・serviceKey）と利用申請方法の案内

2026-09-27の実際の呼び出し結果です。検索、構造の確認、先頭行のプレビューに認証キーは必要ありません。

できることは2段階です

1段階目 · 検索と構造の確認 — インストール・登録なしですぐに利用可能

• 会話で検索：「ソウルの公営駐車場の位置データはある？」— 正確な単語でなくても、意味が通じれば見つけます
• 列で検索：「緯度・経度・病院名が一緒にあるデータ」
• 構造をプレビュー：どんな列が含まれているか、先頭の数行がどのようになっているか
• 入手方法を案内：どこから、どのように入手できるかをお知らせします

この段階は公開リモートサーバー（https://datagokr.dev/mcp）が処理します。キーもログインも必要ありません。

2段階目 · 利用申請とデータの取得 — 自分のコンピューターにプログラムが必要（Claudeウェブ・ChatGPTでは利用できません）

• 一言で利用申請。 ポータルではデータセットごとに詳細ページを開き、申請ボタンを押して、目的の選択・説明の入力・規約への同意を繰り返す必要があります。ここでは「これらのデータを利用申請して」と一言伝えるだけで、最大50件を一括申請できます。自動承認のデータなら、すぐに使えます。
• 自分のAPIキーでそのまま取得。 APIドキュメントを読んでURLにキーを付けて直接呼び出す必要はありません。「このAPIからデータを数行取得して」と言えば、自分のキーで取得します。
• ファイルのダウンロードも言葉で。 データセットごと、過去のバージョンごとにダウンロードボタンを押す必要はありません。「このデータを全部ダウンロードして」と言えば、過去のバージョンもまとめて取得し、Excelで韓国語が文字化けしないUTF-8ファイルも一緒に作成します。

2段階目は自分のdata.go.krアカウントとAPIキーを使って行います。アカウントやキーが他人のサーバー（当サーバーを含む）を経由しないように、自分のコンピューターからポータルへ直接接続するプログラム（このパッケージ）が処理します。

自分のアプリではどこまでできますか？

使用するアプリ	1段階目の検索	2段階目の申請・取得	インストール
Claudeデスクトップ（Windows・Mac）	✅	✅	インストールファイルをダブルクリック
Claudeウェブ（claude.ai）・ChatGPT（ウェブ・アプリ）	✅	❌ data.go.krから直接	コネクターのURLを接続
ターミナル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。または、エージェントに Fetch and execute the setup instructions from https://datagokr.dev/agent-setup/prompt.md の1行を貼り付けてください。

---

以下は開発者向けの詳細ドキュメントです。

ステップ2のプログラム（このパッケージ）が自分のコンピューターで行うこと

検索・構造確認・先頭行のプレビューは、公開リモート MCP サーバー（https://datagokr.dev/mcp）を登録するだけで完了し、何もインストールしません。ファイルの全体ダウンロード、利用申請、自分のキーを使ったオープン 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行を返します。検索順位・全行数・行の内容はポータルの更新によって変わります。CLI 実行ファイルの代わりに python -m datagokr も使用できます。

元データ全体を保存するには、次を実行します。このコマンドは先頭5行ではなく標準データ全体を CSV で保存するため、時間がかかる場合があります。

datagokr download 15012896 --out ./downloads

応答の path が実際の保存先です。既定の保存場所は ~/datagokr/<dataset_id>/ で、--out を指定するとそのディレクトリに保存します。同じパスのファイルは上書きされます。

AI エージェントに1行でインストールさせる

Claude Code・Codex・Cursor など、どのエージェントでも、以下の文をそのまま渡せばクライアントを検出してリモートサーバーを登録し、検索を1回行って検証まで実施します。

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つの名前を 名前=値 の形式で記述します。シェルコマンドの実行や ${変数} の置換には対応していません。MCP の作業ディレクトリは AI クライアントごとに異なる場合があるため、プロジェクトの .env に依存する場合は実行場所を確認してください。

キーなしで1回だけ実行したり、出力先のパスを変更したりすることもできます。

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 Web・ChatGPT（コネクター、ステップ 1 のみ）

ローカルプログラムを実行できないアプリのため、リモートサーバーのみをコネクターとして接続します（Claude デスクトップには、以下の拡張ファイルをおすすめします）。Claude は「設定」→「コネクター」→「追加」→「カスタムコネクター」で、名前は任意に設定し、URL に https://datagokr.dev/mcp（末尾の /mcp まで）を入力して接続します。詳細設定の OAuth クライアント ID・シークレットは空欄にします。接続時の承認は、ログイン画面なしで自動的に完了します。ChatGPT（Web・アプリ）は「設定」→「統合」→「プラグイン」→「追加」→「MCP アプリを作成」で同じ URL を入力し、認証は OAuth に設定します（メニュー名はバージョンや料金プランによって異なる場合があります）。検索・構造の確認・プレビュー（ステップ 1）はできますが、利用申請・自分のキーの照会・全件ダウンロード（ステップ 2）はできません。必要に応じて、AI が案内する data.go.kr のページで直接行います。

Claude デスクトップ（Windows・Mac）

ステップ 1・2 の両方に対応しています。ファイル 1 つで、このコンピューターに検索・照会・利用申請・ダウンロードのツールをインストールします。最新の 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 アプリのインストールと実際のポータルログインは、実機での検証前です。

従来の手動登録も可能です。インストールした実行ファイルを claude_desktop_config.json の mcpServers に "datagokr-local": {"command": "/absolute/path/to/.venv/bin/datagokr-mcp"} として追加します。拡張機能からインストールした場合、同じローカルサーバーを重複して登録する必要はありません。

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 を実行します。直接設定する場合は、CLI で登録する代わりに ~/.codex/config.toml に追加します。

[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에 따른 정상 경로; 반환된 안내와 파일 확인
원문이 없거나 빈 파일 안내	포털 상세 페이지와 제공기관 링크 확인; 모든 카탈로그 항목이 다운로드 가능한 파일인 것은 아님