Taiwan Judicial Judgments 台灣司法判決書

• 四個 MCP 工具 — 裁判書全文關鍵字搜尋、透過 ID 取得全文、PDF 下載、法律名詞查詢
• stdio JSON-RPC 2.0 — 標準 MCP 傳輸協定
• @mcp.tool() 裝飾器 — Pydantic 型別化工具註冊
• 兩步驟抓取 — 處理司法院網站以 iframe 呈現搜尋結果的特殊架構
• 無需認證 — 司法院裁判書系統為公開端點
• 獨立解析層 — parser/ 模組與 HTTP 連接器分離，可離線測試（搭配 fixtures）

You： 最近有哪些和著作權有關的判決

AI call： tw-judgment - search_judgments (MCP)(keyword: "著作權")

{
  "keyword": "著作權",
  "total":   55265,
  ...
}

Result： 以下是最近的著作權相關判決（共 55,265 筆，以下列出最新 10 件核心案件）：

115.04.15 │ 智慧財產及商業法院   │ 114年民著訴52 │ 侵害著作權有關人格權爭議
...

You： 請告訴我 114年民著訴52 的詳細資訊

AI call： tw-judgment - get_judgment (MCP)(judgment_id: "IPCV,114,民著訴,52,20260415,1")

{
  "title": "智慧財產及商業法院 114 年度民著訴字第 52 號民事判決",
  "date":  "民國 115 年 04 月 15 日",
  "case_reason": "侵害著作權有關人格權爭議",
  "content": "……全文字串……",
  "paragraphs": [
    {"id": "主文", "section": "主文", "level": 1, "heading": null, "text": "……"},
    {"id": "事實及理由.一", "section": "事實及理由", "level": 2, "heading": "原告主張：", "text": ""},
    {"id": "事實及理由.一.(一)", "section": "事實及理由", "level": 3, "heading": null, "text": "……"},
    ...
  ]
}

Result： 本件爭點為…（AI 直接引用 事實及理由.一.(一) 段落內容）

You： 把這份判決的 PDF 抓下來放桌面，我要附在書狀當證物

AI call： tw-judgment - get_judgment_pdf (MCP)(judgment_id: "IPCV,114,民著訴,52,20260415,1", save_to: "~/Desktop")

{
  "judgment_id": "IPCV,114,民著訴,52,20260415,1",
  "url":         "https://judgment.judicial.gov.tw/FILES/IPCV/114%2c%e6%b0%91%e8%91%97%e8%a8%b4%2c52%2c20260415%2c1.pdf",
  "path":        "/Users/you/Desktop/IPCV,114,民著訴,52,20260415,1.pdf",
  "size_bytes":  245678,
  "cached":      false
}

Result： 已下載到 ~/Desktop/IPCV,114,民著訴,52,20260415,1.pdf，可直接附入書狀當證物。

提醒：設定環境變數 MCP_TW_JUDGMENT_DOWNLOAD_DIR=~/Downloads/tw-judgments 後，呼叫 get_judgment_pdf 時省略 save_to 會自動存到該資料夾；兩者都沒設定則只回傳 URL，不下載。

# 安裝依賴
uv sync

# 連線檢查
uv run python scripts/auth/test_connection.py

# 本地啟動伺服器
uv run mcp-tw-judgment

# 離線測試（parser + tool 註冊）
uv run python -m unittest tests.test_judgment_parser tests.test_all_tools -v

# 即時 API 測試（會呼叫司法院端點）
RUN_LIVE_TESTS=1 uv run python -m unittest tests.test_all_tools -v

新增工具請見 CONTRIBUTING.md。

MIT License — 詳見 LICENSE。

• Python 3.12+
• uv（建議）或 pip

方式 1 — uvx（不安裝，按需執行）

uvx mcp-tw-judgment

方式 2 — pip / uv pip

pip install mcp-tw-judgment
# 或
uv pip install mcp-tw-judgment

安裝後可直接使用 mcp-tw-judgment 指令。

方式 3 — 由原始碼安裝

git clone https://github.com/asgard-ai-platform/mcp-tw-judgment.git
cd mcp-tw-judgment
uv sync
uv run mcp-tw-judgment

伺服器透過 stdio 走 MCP 協定，依你的 client 加入設定:

Claude Desktop

~/Library/Application Support/Claude/claude_desktop_config.json（macOS） 或 %APPDATA%\Claude\claude_desktop_config.json（Windows）:

{
  "mcpServers": {
    "tw-judgment": {
      "command": "uvx",
      "args": ["mcp-tw-judgment"]
    }
  }
}

Claude Code

加到專案 .mcp.json:

{
  "mcpServers": {
    "tw-judgment": {
      "command": "uvx",
      "args": ["mcp-tw-judgment"]
    }
  }
}

Cursor

~/.cursor/mcp.json:

{
  "mcpServers": {
    "tw-judgment": {
      "command": "uvx",
      "args": ["mcp-tw-judgment"]
    }
  }
}

環境變數

MCP server 是由 client（Claude Desktop、Claude Code、Cursor）啟動的，不是從你的 shell 啟動——所以在 ~/.zshrc、~/.bashrc 裡 export 變數不會傳到 server。必須在 client 設定檔的 env 區塊設：

{
  "mcpServers": {
    "tw-judgment": {
      "command": "uvx",
      "args": ["mcp-tw-judgment"],
      "env": {
        "MCP_TW_JUDGMENT_DOWNLOAD_DIR": "~/Downloads/tw-judgments"
      }
    }
  }
}

依你用的 client 把上面的 env 加到對應設定檔（claude_desktop_config.json、.mcp.json 或 ~/.cursor/mcp.json）。改完後重啟 client 才會生效。

You： 最近有哪些和著作權有關的判決

AI call： tw-judgment - search_judgments (MCP)(keyword: "著作權")

{
  "keyword": "著作權",
  "total":   55265,
  ...
}

Result： 以下是最近的著作權相關判決（共 55,265 筆，以下列出最新 10 件核心案件）：

115.04.15 │ 智慧財產及商業法院   │ 114年民著訴52 │ 侵害著作權有關人格權爭議
...

You： 請告訴我 114年民著訴52 的詳細資訊

AI call： tw-judgment - get_judgment (MCP)(judgment_id: "IPCV,114,民著訴,52,20260415,1")

{
  "title": "智慧財產及商業法院 114 年度民著訴字第 52 號民事判決",
  "date":  "民國 115 年 04 月 15 日",
  "case_reason": "侵害著作權有關人格權爭議",
  "content": "……全文字串……",
  "paragraphs": [
    {"id": "主文", "section": "主文", "level": 1, "heading": null, "text": "……"},
    {"id": "事實及理由.一", "section": "事實及理由", "level": 2, "heading": "原告主張：", "text": ""},
    {"id": "事實及理由.一.(一)", "section": "事實及理由", "level": 3, "heading": null, "text": "……"},
    ...
  ]
}

Result： 本件爭點為…（AI 會直接引用 事實及理由.一.(一) 這段）

You： 把這份判決的 PDF 抓下來放桌面，我要附在書狀證物裡

AI call： tw-judgment - get_judgment_pdf (MCP)(judgment_id: "IPCV,114,民著訴,52,20260415,1", save_to: "~/Desktop")

{
  "judgment_id": "IPCV,114,民著訴,52,20260415,1",
  "url":         "https://judgment.judicial.gov.tw/FILES/IPCV/114%2c%e6%b0%91%e8%91%97%e8%a8%b4%2c52%2c20260415%2c1.pdf",
  "path":        "/Users/you/Desktop/IPCV,114,民著訴,52,20260415,1.pdf",
  "size_bytes":  245678,
  "cached":      false
}

Result： 已下載到 ~/Desktop/IPCV,114,民著訴,52,20260415,1.pdf。

Tip: Set MCP_TW_JUDGMENT_DOWNLOAD_DIR=~/Downloads/tw-judgments to have every call download to that folder by default; omit save_to in the call and the tool returns the URL only (no download).

mcp-tw-judgment/
├── app.py                       # FastMCP 單例
├── mcp_server.py                # 入口（stdio 傳輸）
├── config/settings.py           # API 基礎 URL、端點、請求標頭
├── connectors/rest_client.py    # HTTP GET helper（含重試 + 編碼偵測）
├── auth/none.py                 # 無認證模組（公開 API）
├── parser/
│   ├── judgment_parser.py       # 純 HTML 解析：裁判書（不含 HTTP）
│   └── terms_parser.py          # 純 HTML 解析：用語辭典（不含 HTTP）
├── tools/judgment_tools.py      # MCP 工具定義
├── tests/
│   ├── fixtures/                # 儲存的 HTML 回應（供離線單元測試使用）
│   ├── test_judgment_parser.py  # 單元測試（無需網路）
│   ├── test_terms_parser.py     # 用語辭典解析器單元測試（無需網路）
│   └── test_all_tools.py        # 工具測試（即時 API，需 RUN_LIVE_TESTS=1）
└── scripts/auth/test_connection.py

本專案直接使用司法院裁判書系統的公開查詢介面，非官方 API。

請注意： 本工具僅供個人查詢與研究使用。請勿進行大量自動化存取或爬取，以免對司法院伺服器造成負擔。使用前請自行評估是否符合司法院網站的使用條款。