MCP 服务器

smartfarm-mcp

Wraps the Smart Farm Korea Open API into MCP tools, allowing LLMs to query farm environment data using friendly metric names like temperature, humidity, and CO2.

README

smartfarm-mcp

스마트팜코리아 "스마트팜 빅데이터 제공 서비스" Open API(data.go.kr 15121334)를 MCP 도구로 감싼 서버. LIVE 검증 완료 (HTTPS, serviceKey path 방식). 소비자(LLM)는 원시 코드(fldCode/sectCode/fatrCode)를 몰라도 내부기온·습도· co2 같은 친화적 metric 이름으로 부른다.

빠른 시작

git clone <this-repo>
cd smartfarm-mcp
pip install -r requirements.txt

# 인증키: data.go.kr 15121334 활용신청 후 발급 → .env 에 넣기
cp .env.example .env
# .env 의 SMARTFARM_SERVICE_KEY 값을 본인 키로 수정

python test_local.py          # 키 있으면 LIVE, 없으면 MOCK

키 로드 우선순위: 환경변수 SMARTFARM_SERVICE_KEY → ./.env → 상위 ../.env. .env 는 .gitignore 로 커밋에서 제외됩니다(키 유출 방지).
키 없이 구조만 보려면: SMARTFARM_MOCK=1 python test_local.py

MCP 클라이언트 등록 (.mcp.json)

{
  "mcpServers": {
    "smartfarm-mcp": {
      "command": "python",
      "args": ["/home/k821209/works/ai-breeding/smartfarm-mcp/server.py"]
    }
  }
}

(키는 .env 에서 자동 로드되므로 env 블록 불필요. 명시하려면 "env": {"SMARTFARM_SERVICE_KEY": "..."} 추가.)

tool (LIVE 검증)

tool	설명	op
server_info	서버·데이터 개요	—
list_farms	농가·시설 목록(item 코드→이름)	getIdentityDataList
list_croppings(user_id)	농가의 작기 목록	getCroppingSeasonDataList/{userId}
get_cropping_environment(csn, page, metric?)	작기 환경 시계열(디코딩)	CropseasonRestService/getCroppingSeasonEnvDataList
latest_climate(csn)	가장 최근 내부 환경 1세트	(위 2회 호출)
aggregate_cropping_environment(csn, metric, agg)	기간 집계 mean/min/max	—
get_environment(facility, date, metric)	시설·날짜 환경 시간별 시계열(itemCode 자동)	getEnvDataList

환경 metric (sectCode, fatrCode)

EI/TI 내부기온℃ · EI/HI 내부습도% · EI/CI CO2ppm · EO/TE 외부기온℃ · EO/SR 일사 · EO/WS 풍속 · EO/WD 풍향 (EI/DT, EL/TL, NT/HL 은 의미 미확정 → raw 노출)

검증 예 (PFS_0000001 / 토마토 / cropping 4940)

환경: co2 508ppm · 내부습도 87.33% · 내부기온 19.67℃ (2021-10-01)
최근: 내부기온 25℃ · 습도 99% · co2 607ppm (2022-07-29)
집계: 내부기온 평균 18.05℃

완료 (모든 항목 라이브 검증)

✅ itemCode→작물명: 작기명 근거로 30여 종 매핑(토마토·딸기·파프리카·오이·국화· 참외 등). 모호/복합 코드(060300·100500 등)는 의도적으로 제외(item=None).
✅ env metric 코드: 기술명세서 v2.0 으로 확정 (DT 노점온도·SR 일사량·TL 지온· HL 관수량). 전체 코드표는 공식 명세서 참조: https://smartfarmkorea.net/file/download.do?type=BLANK&fileName=openapiSmartfarm.zip
✅ get_environment(getEnvDataList): 라이브 검증 완료, itemCode 시설에서 자동 보강.