Skip to main content
Glama
MCP Taiwan Judgment Search

MCP Taiwan Judgment Search

MCP Taiwan Judgment Search

PyPI version Python License: MIT MCP GitHub stars GitHub issues GitHub last commit

An MCP server for searching Taiwan judicial judgments, exposing AI-callable tools over Model Context Protocol (MCP).

繁體中文

Features

  • Four MCP tools — full-text search, full-document fetch by ID, PDF download, and legal-term lookup

  • stdio JSON-RPC 2.0 — standard MCP transport protocol

  • @mcp.tool() decorator — Pydantic-typed tool registration

  • Two-step scraping — handles the judicial site's iframe-based result rendering

  • No-auth public endpoint — 司法院裁判書系統 is fully public; no API keys required

  • Pure HTML parser layer — parser/ is decoupled from HTTP and tested offline with saved fixtures

Related MCP server: aluris-caselibrary-mcp

Available Tools

Tool

Description

search_judgments

Full-text keyword search across all judicial judgments. Paginated 20 per page. Returns judgment_id, title, ruling date, case reason, URL, and a text preview per entry.

get_judgment

Fetch the complete text and metadata of a single judgment by its judgment_id. Returns both a flat content string and a structured paragraphs list (each entry has id/section/level/heading/text — e.g. 理由.一.(三).2) for precise citation.

lookup_legal_term

Look up a legal term in the 司法院裁判書用語辭典. Returns definitions for each applicable legal domain (民事、刑事、行政、家事). Optionally filter by domain.

get_judgment_pdf

Return or download a judgment's PDF. When save_to (arg) or MCP_TW_JUDGMENT_DOWNLOAD_DIR (env) is set, the file is saved locally and the path is returned; otherwise only the URL is returned.

Requirements

  • Python 3.12+

  • One of: uv (recommended) or pip

Installation

Option 1 — uvx (no install, runs on demand)

uvx mcp-tw-judgment

Option 2 — pip / uv pip

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

After install, the mcp-tw-judgment console script is available.

Option 3 — From source

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

Usage

The server speaks MCP over stdio. Add it to your client of choice:

Claude Desktop

~/Library/Application Support/Claude/claude_desktop_config.json (macOS) or %APPDATA%\Claude\claude_desktop_config.json (Windows):

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

Claude Code

Add to your project's .mcp.json:

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

Cursor

~/.cursor/mcp.json:

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

Environment Variables

Variable

Effect

MCP_TW_JUDGMENT_DOWNLOAD_DIR

Default directory for get_judgment_pdf downloads. ~ is expanded. If unset and the tool's save_to arg is None, get_judgment_pdf returns the URL without downloading.

MCP servers are launched by the MCP client (Claude Desktop, Claude Code, Cursor), not by your shell — exporting a variable in ~/.zshrc or ~/.bashrc will not reach the server. Set variables in the client config's env block:

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

Apply this to whichever client config you use (claude_desktop_config.json, .mcp.json, or ~/.cursor/mcp.json). Restart the client after editing.

Example Tool Usage

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).

Project Structure

mcp-tw-judgment/
├── app.py                       # FastMCP singleton
├── mcp_server.py                # Entry point (stdio transport)
├── config/settings.py           # API base URL, endpoints, request headers
├── connectors/rest_client.py    # HTTP GET helper with retry + encoding detection
├── auth/none.py                 # No-op auth module (public endpoint)
├── parser/
│   ├── judgment_parser.py       # Pure HTML parsers for judgments (no HTTP)
│   └── terms_parser.py          # Pure HTML parsers for 用語辭典 (no HTTP)
├── tools/judgment_tools.py      # MCP tool definitions
├── tests/
│   ├── fixtures/                # Saved HTML responses for offline unit tests
│   ├── test_judgment_parser.py  # Unit tests (no network)
│   ├── test_terms_parser.py     # Unit tests for terms parser (no network)
│   └── test_all_tools.py        # Tool tests (live API, opt-in via RUN_LIVE_TESTS=1)
└── scripts/auth/test_connection.py

Development

# Setup
uv sync

# Connection check
uv run python scripts/auth/test_connection.py

# Run server locally
uv run mcp-tw-judgment

# Offline tests (parser + tool registration)
uv run python -m unittest tests.test_judgment_parser tests.test_all_tools -v

# Live API tests (hits 司法院 endpoint)
RUN_LIVE_TESTS=1 uv run python -m unittest tests.test_all_tools -v

See CONTRIBUTING.md for adding new tools.

License

MIT License — see LICENSE for details.

Data Source & Disclaimer

This project directly scrapes the 司法院裁判書系統 public search interface — this is not an official API.

Please note: This tool is intended for personal research and ad-hoc queries only. Do not use it for bulk automated access or scraping, as this may place undue load on the judicial system's servers. Use at your own discretion and in accordance with the website's terms of use.

Available Tools

4 tools
get_judgmentA

取得單一裁判書的完整內容,包含案件資訊與全文。

Inputs: judgment_id (required).

get_judgment_pdfA

取得裁判書 PDF 連結,可選擇直接下載到本機。

回傳 dict 一定包含 judgment_id 與 url;當實際下載時另含 path、size_bytes、cached。

Inputs: judgment_id (required), save_to.

search_judgmentsA

搜尋司法院裁判書全文,回傳符合關鍵字的裁判書清單。

每筆結果包含 judgment_id(可傳入 get_judgment 取得全文)、標題、裁判日期、
案由、摘要片段。

Inputs: keyword (required), page.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    A4.2/5.0

    Scored across 4 tools

    Disambiguation5/5

    Each tool serves a distinct purpose: retrieving full judgment text, getting PDF links, looking up legal terms, and searching judgments. No functional overlap.

    Naming Consistency5/5

    All tool names follow a consistent verb_noun pattern in snake_case (get_judgment, get_judgment_pdf, lookup_legal_term, search_judgments), making them predictable.

    Tool Count5/5

    With 4 tools covering search, retrieval, PDF download, and legal term lookup, the count is well-scoped for a judgment search server—neither too few nor too many.

    Completeness5/5

    The tool surface covers the complete workflow: search for judgments, retrieve full text or PDF, and look up legal terms. No obvious gaps for the intended domain.

    Maintenance

    ActivityInactive
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers