law-search-mcp

한국 법령정보센터(law.go.kr) 공식 Open API를 통해 판례를 검색하는 MCP 서버.

• Transport: stdio (FastMCP)
• Backend: law.go.kr/DRF/lawSearch.do + law.go.kr/DRF/lawService.do
• 인증: OC 파라미터 (law.go.kr 신청 시 발급되는 사용자 식별자)

---

설치 & 실행

cd /data_raid/ruci_workspace/law-search-mcp
uv sync                              # .venv 생성 + 의존성 설치
echo "LAW_API_OC=your-oc-id" > .env  # 실제 값으로 교체 (law.go.kr 신청 시 발급)
.venv/bin/python server.py           # MCP stdio 서버 시작

Claude Code MCP 등록

~/.claude.json 또는 프로젝트 .mcp.json:

{
  "mcpServers": {
    "law-search": {
      "command": "/data_raid/ruci_workspace/law-search-mcp/.venv/bin/python",
      "args": ["/data_raid/ruci_workspace/law-search-mcp/server.py"]
    }
  }
}

---

환경 변수

변수	필수	기본값	설명
LAW_API_OC	✅	contact	law.go.kr OpenAPI 식별자. 발급 신청: https://open.law.go.kr

---

MCP Tools

1) search_precedents(query, max_results, page, sort, org, date_range)

판례 목록을 키워드로 검색.

파라미터	타입	기본값	설명
query	str	(필수)	검색 키워드 (예: "상속세 채무공제", "부당행위계산")
max_results	int	20	페이지당 결과 수 (최대 100)
page	int	1	페이지 번호
sort	str	""	"date" = 선고일자순, 빈값 = 관련도순
org	str	""	법원종류코드. 400201 = 대법원
date_range	str	""	YYYYMMDD~YYYYMMDD (예: "20200101~20251231")

반환: 사건명·법원명·선고일자·사건번호·판례일련번호(precSeq) 포함 목록 텍스트.

2) get_precedent_detail(precedent_id)

특정 판례 상세 본문 조회 (판시사항/판결요지/참조조문/참조판례/판례내용 전문).

파라미터	타입	설명
precedent_id	str	search_precedents가 반환한 판례일련번호

---

⚠️ 핵심 제약 — 반드시 읽기

상세 조회는 사실상 대법원 판례만 가능

law.go.kr 공식 OpenAPI의 정책상, get_precedent_detail은 대법원 판결문에 대해서만 전문을 반환합니다. 고등법원·행정법원·지방법원·조세심판원 결정문은 검색 목록에는 나오지만 상세 조회 시 다음과 같이 응답:

{"Law": "일치하는 판례가 없습니다.  판례명을 확인하여 주십시오."}

실측 결과 (2026-05-19, query="부당행위계산" org=400201 display=10 기준):

• 검색 결과 10건 중 법원명="대법원"으로 채워진 건은 1건뿐
• 그 1건만 상세 조회 성공, 나머지 9건은 모두 위 에러

권장 사용 패턴

# 1. 검색 (관련도순 or 날짜순 모두 OK)
results = search_precedents(query="...", max_results=50)

# 2. 응답 텍스트에서 [court='대법원'] 인 항목만 골라낸 뒤
#    그 항목의 판례일련번호로만 detail 조회
#    (org=400201 필터를 걸어도 90%는 법원명이 빈 문자열이므로 사후 필터 필수)

# 3. 대법원 외 판례 본문이 필요하다면:
#    - 조세심판원/국세청 자료는 별도 데이터셋(예: papers.db) 활용
#    - 하급심 판결문은 대법원 종합법률정보(glaw.scourt.go.kr) 등 별도 경로 필요

---

응답 구조 (디버깅용)

검색 응답 — lawSearch.do

{
  "PrecSearch": {
    "totalCnt": 14,
    "prec": [
      {
        "판례일련번호": "241203",
        "사건명": "...",
        "사건번호": "...",
        "선고일자": "20250207",   // YYYYMMDD
        "법원명": "대법원",        // ← 비어있으면 detail 조회 불가 가능성 높음
        "사건종류명": "세무",
        "판결유형": "...",
        "선고": "..."
      }
    ]
  }
}

prec는 결과가 1건이면 dict, 2건 이상이면 list로 옴 → 코드는 dict→list 변환 처리됨.

상세 응답 — lawService.do (성공)

{
  "PrecService": {
    "사건명": "...", "사건번호": "...", "선고일자": "...",
    "법원명": "대법원", "사건종류명": "...", "판결유형": "...",
    "판시사항": "...", "판결요지": "...",
    "참조조문": "...", "참조판례": "...",
    "판례내용": "..."   // 판결문 전문
  }
}

상세 응답 — lawService.do (실패: 대법원 외 ID)

{ "Law": "일치하는 판례가 없습니다.  판례명을 확인하여 주십시오." }

---

알려진 이슈

🐛 server.py — Law wrapper 에러를 빈 결과로 silent fail

get_precedent_detail() 의 응답 파싱 로직 (server.py:198):

item = data.get("PrecService", data) if isinstance(data, dict) else data

응답이 {"Law": "일치하는 판례가 없습니다."} 일 때 fallback인 data 전체가 item이 되고, item.get("사건명", "") 등이 모두 빈 문자열을 반환 → 사용자에게는 "빈 판례 정보"로 보임. 에러 메시지를 명시적으로 surfacing 하는 로직 추가 필요:

# 권장 수정 (server.py:197~ 부근)
if isinstance(data, dict) and "Law" in data and "PrecService" not in data:
    return f"오류: 상세 조회 실패 — {data['Law']}\n" \
           f"(law.go.kr 상세 API는 대법원 판례만 지원합니다. " \
           f"precedent_id={precedent_id}의 법원명을 확인해주세요.)"
item = data.get("PrecService", data)

---

빠른 동작 확인

.env 설정 후:

.venv/bin/python -c "
import asyncio, httpx
async def t():
    async with httpx.AsyncClient(timeout=30) as c:
        r = await c.get('http://www.law.go.kr/DRF/lawSearch.do',
            params={'OC':'your-oc-id','target':'prec','type':'JSON',
                    'query':'부당행위계산','display':'3'})
    print(r.json()['PrecSearch']['totalCnt'], '건 검색됨')
asyncio.run(t())
"

검색 건수가 양수면 정상.

---

FINO 프로젝트 사용 메모

• NTS 검색 데이터(papers.db): 조세심판원 결정문·하급심 판례 (289K건) — 이미 보유 중
• law-search-mcp 보강 용도:
  • 사용자가 특정 대법원 판례를 지정 인용할 때 풀텍스트 fetch
  • 최신 대법원 판례 (papers.db 크롤 이후 시점) 보강
• 하급심/심판례 검색: 본 MCP는 검색 메타데이터만 활용, 본문은 papers.db에서 매칭 (사건번호 기준)