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

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

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.