mcp-tw-judgment 0.3.0

MCP server for searching Taiwan judicial judgments (司法院裁判書系統) — AI-callable tools over Model Context Protocol

MCP Taiwan Judgment Search

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

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.