mcp-taiwan-legal-db

mcp-taiwan-legal-db

English · 繁體中文

台灣法規、裁判書、憲法法庭裁判 — MCP Server。

讓任何 MCP 相容的 AI 助手直接存取台灣公開法律資料：

• 司法院裁判書 — judgment.judicial.gov.tw（全文搜尋 + 取得）
• 全國法規資料庫 — law.moj.gov.tw（11,700+ 部法規）
• 憲法法庭 — cons.judicial.gov.tw（868 筆大法官解釋 + 憲判字，含理由書全文，離線快取）

以 Python 搭配 MCP Python SDK 寫成。純工具 wrapper，只連線台灣政府官方來源（詳見下方「資料來源與統計」），不發送任何其他網路請求；憲法法庭資料為內建離線打包。

---

特色

功能	說明
8 個 MCP 工具	裁判書搜尋/全文、法規查詢、釋字/憲判字查詢、引用關係圖譜
離線快取	868 筆大法官解釋與憲判字（含理由書全文，以及從官網 PDF 擷取的大法官意見書全文）從本地資料即時回傳
引用關係圖譜	從理由書抽取所有引用的釋字/憲判字，追溯憲法學說演變
全文搜尋	裁判書關鍵字搜尋 + 釋字爭點/理由書全文搜尋
混合請求策略	預設用 httpx 直打（~0.25s），觸發司法院 F5 WAF 時自動以 Playwright 刷 cookie 後繼續

---

⚡ 安裝（PyPI，推薦）

pip install mcp-taiwan-legal-db

Debian / Ubuntu / WSL 注意：系統 Python 受 PEP 668 保護，直接 pip install 會被擋。請改用：

• pipx install mcp-taiwan-legal-db（推薦，自動建隔離 venv，CLI tool 標準裝法）
• 或 pip install --user --break-system-packages mcp-taiwan-legal-db

Windows / 企業部署：建議用 uv 或 pipx 裝成獨立工具，不碰系統 Python 的 site-packages：

uv tool install mcp-taiwan-legal-db
uv tool update-shell   # 把工具目錄加進 PATH，重開終端機後生效

請每位使用者各自安裝（預設裝在使用者目錄）。伺服器執行時會把查詢快取與法規代碼表更新寫在套件目錄旁，裝到 C:\Program Files 這類一般使用者無法寫入的共用位置會啟動失敗，目前不支援全使用者共用安裝。

裝完後 entry point mcp-taiwan-legal-db 會在 PATH 上。接到 Claude Code（任何專案都能用）：

claude mcp add taiwan-legal-db mcp-taiwan-legal-db --scope user

接著 /mcp 重啟連線、Claude 就會在自然語言查詢時自動用 8 個 MCP tool。

Chromium（司法院 WAF fallback）：v1.1.0 起會在第一次需要時自動下載安裝，不用手動處理。無法連外下載的環境請預先安裝：

uvx --from mcp-taiwan-legal-db playwright install chromium    # 僅在司法院 WAF 觸發時使用，平時 idle

---

開發環境設置

下面是 clone 來修程式 / 跑測試的流程：

# 1. Clone repo
git clone https://github.com/lawchat-oss/mcp-taiwan-legal-db.git
cd mcp-taiwan-legal-db

# 2. 建立並初始化虛擬環境
python3 -m venv .venv
.venv/bin/pip install --upgrade pip
.venv/bin/pip install -e .

# 3. 安裝 Playwright Chromium（僅在司法院 WAF 觸發時使用，一般查詢不會啟動）
.venv/bin/playwright install chromium

# 4. 驗證伺服器可以啟動並註冊 8 個工具
.venv/bin/python -c "
import asyncio
from mcp_server.server import mcp
print('Server:', mcp.name)
tools = asyncio.run(mcp.list_tools())
print('Tools:', [t.name for t in tools])
assert len(tools) == 8, f'Expected 8 tools, got {len(tools)}'
print('✓ Setup OK')
"

預期輸出：

Server: 台灣法律資料庫
Tools: ['search_judgments', 'get_judgment', 'query_regulation', 'get_pcode', 'search_regulations', 'get_interpretation', 'search_interpretations', 'get_citations']
✓ Setup OK

上面沒報錯就完成了。Repo 根目錄已經帶一份 .mcp.json，任何在此資料夾內開的 Claude Code session 會自動載入這個 server，不需要額外註冊。

---

有什麼工具可以用

8 個 MCP 工具，全部唯讀，全部只打台灣政府的公開資料庫。

法規與裁判

工具	用途	典型呼叫
search_judgments	搜尋司法院裁判書資料庫	search_judgments(keyword="預售屋 遲延交屋", case_type="民事")
get_judgment	依 JID 或 URL 取得單筆判決全文	get_judgment(jid="TPSM,114,台上,3753,20251112,1")
query_regulation	查詢法規條文／範圍／全文／修法沿革	query_regulation(law_name="民法", article_no="184")
get_pcode	將法規名稱解析為 pcode（法規代號）	get_pcode(law_name="律師法")
search_regulations	以關鍵字搜尋 11,700+ 部法規	search_regulations(keyword="勞動")

憲法法庭

工具	用途	典型呼叫
get_interpretation	大法官解釋/憲判字全文（離線快取）	get_interpretation("釋字748", reasoning_keyword="婚姻")
search_interpretations	搜尋釋字/憲判字（爭點 + 理由書全文）	search_interpretations(keyword="集會自由")
get_citations	引用關係圖譜（往前追溯）	get_citations("釋字748", include_context=True)

工具細節

搜尋司法院判決系統。支援：

• 精確案號查詢（快，HTTP GET）：設定 case_word + case_number + year_from
• 全文關鍵字搜尋：設定 keyword
• 裁判主文篩選：main_text="被告應將 移轉" + keyword="借名登記" → 找被告敗訴的借名登記案
• 可依 court、case_type（民事／刑事／行政／懲戒）、year_from／year_to 過濾
• 結果自動依法院層級排序（最高 → 高等 → 地方）
• 資料涵蓋範圍：民國 89 年（2000）起接近完整，81–88 年（1992–1999）僅零星收錄，80 年（1991）以前查無。這是司法院系統本身的收錄範圍，本工具不做任何年份裁切

重要：要查某個特定案號時，一定要用 case_word+case_number，不要放進 keyword。

# ✅ 正確 — 查 114 台上 3753 最高法院
search_judgments(case_word="台上", case_number="3753", year_from=114, court="最高法院")

# ✅ 正確 — 全文搜尋
search_judgments(keyword="預售屋 遲延交屋")

# ❌ 錯 — 把案號放進 keyword
search_judgments(keyword="114年度台上字第3753號")

取得單筆判決的結構化全文。

• 輸入：jid（從 search_judgments 結果取得）或 url
• 輸出：{case_id, court, date, main_text, facts, reasoning, cited_statutes, cited_cases, full_text, source_url}
• HTTP GET data.aspx 取得全文
• 結果快取 30 天

get_judgment(jid="TPSM,114,台上,3753,20251112,1")

單筆判決可能超過 1 萬 token。建議先用 search_judgments 取得 metadata，只在使用者明確需要時才抓全文。

查詢全國法規資料庫。

# 單一條文
query_regulation(law_name="民法", article_no="184")

# 條文範圍
query_regulation(law_name="民法", from_no="184", to_no="198")

# 完整法規
query_regulation(law_name="律師法")

# 附修法沿革；指定條號時另回傳該條歷次條文（article_history）
query_regulation(law_name="勞動基準法", article_no="24", include_history=True)

指定條號並開啟 include_history 時，article_history.revisions 會列出該條每次制定、增訂、修正、刪除的日期與當時條文，可直接前後對照。只讀取修法沿革中動到該條的歷史版本（例如民法第 184 條只需 36 個版本中的 5 個），版本清單與歷史版本全文都會快取；讀取失敗的版本會列在 failed_versions 並標 partial。

支援 law_name（透過 get_pcode 自動解析 pcode）或直接傳 pcode。子條文如 247-1、15-1 都支援。

取得大法官解釋（釋字第 1–813 號）或憲法法庭裁判（憲判字）全文。預設層從本地 JSON 快取即時回傳。

分層設計（節省 context）：

層級	觸發條件	離線？
預設層（字號/日期/爭點/解釋文）	永遠回傳	✓
理由書片段	reasoning_keyword="關鍵字"	✓
理由書全文（最多 15,000 字）	include_reasoning=True	✓
意見書片段	opinions_keyword="關鍵字"	✓
意見書全文	include_opinions=True	✓
單份意見書全文	opinion_document="許宗力"	✓
超過 15,000 字的意見書續讀後段	opinions_offset=15000（值取自回傳的 opinions_next_offset）	✓

# 預設層（離線，~0ms）
get_interpretation("釋字748")

# 理由書中搜尋關鍵字
get_interpretation("釋字748", reasoning_keyword="婚姻自由")

# 在意見書中定位特定大法官
get_interpretation("釋字758", opinions_keyword="湯德宗")

# 只讀某位大法官的完整意見書（意見書合計過長被截斷時）
get_interpretation("釋字758", opinion_document="許宗力")

# 單份意見書超過 15,000 字被截斷時，用回傳的 opinions_next_offset 續讀
get_interpretation("釋字777", opinion_document="吳陳鐶", opinions_offset=15000)

# 新制憲判字
get_interpretation("111年憲判字第1號")

建議先用 keyword 片段模式定位，只在需要時才開全文模式。

搜尋大法官解釋與憲判字。關鍵字同時匹配標題、爭點、理由書全文。

# 全文搜尋（搜爭點 + 理由書）
search_interpretations(keyword="集會自由")

# 篩選年度（新制）
search_interpretations(keyword="言論自由", year=112)

# 列舉最後 10 筆釋字
search_interpretations(number_from=804, number_to=813)

從理由書中抽取所有引用的釋字/憲判字字號。追溯方向：查詢指定裁判引用了哪些先前裁判。

get_citations("釋字748")
# → citations: [釋字第242號, 釋字第362號, 釋字第365號, ...]

# 附上引用前後 80 字片段
get_citations("釋字748", include_context=True)

---

範例問法

「查民法第 184 條」
「搜尋跟預售屋遲延交屋有關的最高法院判決」
「釋字 748 的理由書重點是什麼」
「哪些大法官解釋討論過集會自由」
「釋字 748 引用了哪些先前的釋字」
「查 111 年憲判字第 1 號」

---

註冊到你的 Claude client

依你使用的 Claude client 選對應的段落。

Claude Code (CLI)

Claude Code 會自動載入專案根目錄的 .mcp.json。這個 repo 已經內建一份：

{
  "mcpServers": {
    "taiwan-legal-db": {
      "command": ".venv/bin/python",
      "args": ["-m", "mcp_server.server"]
    }
  }
}

零設定：cd 進 repo 之後跑 claude 就好。MCP server 列表會看到 taiwan-legal-db，而且此資料夾不會有其他多餘的 server。

跟隊友分享：.mcp.json 已經 commit 進 repo。任何人 clone 下來跟著 Quick Start 跑完，就會自動完成 MCP 註冊。

加到其他專案（你想在另一個資料夾用這個 MCP）：用 claude mcp add 以 project scope 加入：

cd /path/to/your/other/project
claude mcp add taiwan-legal-db --scope project -- \
  /absolute/path/to/mcp-taiwan-legal-db/.venv/bin/python \
  -m mcp_server.server

這會在你另一個專案的根目錄寫出一份 .mcp.json。想在每個專案都能用，把 --scope project 改成 --scope user。

Claude Desktop (macOS / Windows)

Claude Desktop 使用一個全域設定檔：

• macOS：~/Library/Application Support/Claude/claude_desktop_config.json
• Windows：%APPDATA%\Claude\claude_desktop_config.json
• Windows (Microsoft Store / WinGet / MSIX 安裝)：C:\Users\<YourName>\AppData\Local\Packages\Claude_pzs8sxrjxfjjc\LocalCache\Roaming\Claude\claude_desktop_config.json

最快開啟方式：在 Claude Desktop 點選單列（不是視窗）→ Settings → Developer → Edit Config。檔案若不存在 Claude Desktop 會自動建立。

在 mcpServers 下加入以下內容（跟已有內容合併）：

{
  "mcpServers": {
    "taiwan-legal-db": {
      "command": "/absolute/path/to/mcp-taiwan-legal-db/.venv/bin/python",
      "args": ["-m", "mcp_server.server"],
      "cwd": "/absolute/path/to/mcp-taiwan-legal-db"
    }
  }
}

把 /absolute/path/to/mcp-taiwan-legal-db 換成你的實際 clone 路徑。cwd 欄位必填，Python 才找得到 mcp_server 套件。

存檔後，完全關閉並重新開啟 Claude Desktop（不是只關視窗 — macOS 用 ⌘Q、Windows 右鍵工具列圖示 → Quit）。設定檔只會在重啟時重新載入。

Claude Cowork (Pro 以上方案)

Claude Cowork 跑在 Claude Desktop 裡面，共用同一個 claude_desktop_config.json — 沒有另外的 Cowork 設定檔。任何你在 Claude Desktop 註冊的 MCP server 會自動透過 Claude Desktop SDK 橋接進 Cowork 的沙盒 VM。

設定步驟：

1. 照上面 Claude Desktop 段落把 taiwan-legal-db 加進 claude_desktop_config.json
2. 完全關閉並重新開啟 Claude Desktop — 同時也會重啟 Cowork
3. 開一個 Cowork session，taiwan-legal-db 的工具就可以用了

注意：Cowork 目前在 Claude Pro / Max / Team / Enterprise 方案都可以用，且只能存取你明確授權的資料夾。MCP server 本身跑在你的 host 上（不是 Cowork VM 裡面），透過 Desktop SDK bridge 溝通，所以不管你授權哪個資料夾給 Cowork，它都存取得到內建的資料檔。

其他 MCP 相容 client

任何符合 Model Context Protocol 規範 的 MCP client 都可以使用這個 server。啟動指令永遠是：

.venv/bin/python -m mcp_server.server

⋯⋯加上 cwd 設定為 repo 根目錄（Python 才找得到 mcp_server 套件）。設定位置請參考你使用的 client 的文件，找 mcpServers JSON 區塊寫在哪裡。

---

在這個 server 上面建 A2A agent

想用 A2A agent 驅動這些工具？請見 examples/agno-bindu/ — 一個社群貢獻的 A2A agent 範例。

---

疑難排解

ModuleNotFoundError: No module named 'mcp_server' → 你沒有在 venv 裡面跑 pip install -e .。回到 Quick Start 步驟 2。

FileNotFoundError: data/pcode_all.json → 內建的 mcp_server/data/pcode_all.json 不見或被刪了。用 git checkout mcp_server/data/pcode_all.json 還原，或觸發重新下載：

.venv/bin/python -m mcp_server.updater

MCP client 回報「伺服器啟動失敗」 → 直接跑 Quick Start 步驟 3 的驗證指令。若失敗，代表 import chain 壞了 — 看 traceback。若通過，問題在 MCP client 的啟動設定（路徑或 cwd 錯了）。

ssl.SSLCertVerificationError: ... Missing Subject Key Identifier → 這是 OpenSSL 3.6+ 對 TWCA Global Root CA 的廣泛 rejection，不是 certifi 舊的問題。本 repo 透過 truststore 套件讓 Python 改用作業系統原生的 trust store（macOS Security framework、Windows CryptoAPI、Linux 系統 CA），所有路徑都保留完整 SSL 驗證（verify=True），不使用 verify=False。這在 macOS、Windows 以及 OpenSSL <3.6 的 Linux 都能正常工作。OpenSSL 3.6+ 的 Linux 環境（Fedora 40+、未來的 Ubuntu LTS）目前可能仍有問題，歡迎 issue 回報。

---

WAF 處理機制

司法院 judgment.judicial.gov.tw 部署了 F5 BIG-IP ASM WAF，純 HTTP 請求可能被擋（回固定 245 bytes 的 "Request Rejected"）。

本專案採混合策略：

• 預設用 httpx 直接請求（~0.25s）
• 偵測到被擋（response 含 Request Rejected 或 JS challenge marker bobcmn / TSPD）自動 fallback 到 Playwright 跑一次 JS challenge
• 取得 TSPD cookies 後持久化到 mcp_server/data/.judicial_cookies.json（0600 權限，已 gitignore）
• 後續查詢繼續用 httpx 帶 cookies 執行

cons.judicial.gov.tw（釋字）跟 law.moj.gov.tw（法規）沒這個問題，不經過 WAF 流程。

---

資料來源與統計

查詢時實際連網的，只有以下兩個台灣政府公開資料庫網域：

來源	網域	用途
司法院裁判書系統	judgment.judicial.gov.tw	裁判書搜尋與全文（FJUD/Default_AD.aspx、data.aspx）
全國法規資料庫	law.moj.gov.tw	法規條文與修法沿革（LawClass/*）

mcp_server/config.py:ALLOWED_DOMAINS 以硬編碼 allow-list 強制執行（即上列兩個網域），伺服器會拒絕任何不在清單內的 URL。

裁判書年份涵蓋範圍：本工具即時代理司法院系統，沒有自己的資料庫，有效年份 = 司法院收錄範圍。實測（以「竊盜」為關鍵字計數）民國 89 年（2000）起每年數萬筆，81–88 年（1992–1999）合計約 2,000 筆，80 年（1991）以前為零。司法院公告其開放資料檔「收錄範圍與裁判書查詢系統相同」，因此沒有更早的公開來源。查詢 2000 年以前的裁判請預期查無或零星。