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

datagokr

공공데이터포털의 데이터를 검색하고, 자기 키·자기 로그인·자기 디스크로 조회·활용신청·다운로드하는 Python 패키지다. CLI, Python API, 로컬 MCP stdio 서버를 제공한다.

검색과 메타데이터는 공개 원격 MCP 서버를 사용한다. get, fetch, apply, download는 메타데이터를 받은 뒤 사용자 컴퓨터에서 포털에 접속한다. preview는 원격 서버가 본문을 조회하므로, 키를 설정했다면 그 키도 원격 서버로 전송된다. 자세한 전송 범위는 아래 보안 안내를 확인하자.

설치와 첫 조회

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//이고, --out을 주면 그 디렉터리에 저장한다. 같은 경로의 파일은 덮어쓴다.

AI 에이전트에게 한 줄로 설치시키기

클로드 코드·코덱스·커서 등 어떤 에이전트든 아래 문장 하나를 그대로 던지면 클라이언트를 감지해 원격 서버를 등록하고 검색 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 모두 아래 대문자 이름을 사용한다.

여러 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는 같은 네 이름을 이름=값으로 적는다. 셸 명령 실행이나 ${변수} 치환은 지원하지 않는다. MCP의 작업 디렉터리는 AI 클라이언트마다 다를 수 있어 프로젝트 .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

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

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

Shortened. The full README is on GitHub.