mcp-tw-ly 0.1.0

MCP Server for Legislative Yuan information in Taiwan — AI-callable tools via Model Context Protocol

mcp-tw-ly

MCP server for querying Taiwan's Legislative Yuan (立法院) public data via the Legislative Yuan API v2. Built on Model Context Protocol (MCP) over stdio JSON-RPC 2.0.

繁體中文

Features

• No authentication required — public API, no API keys needed
• @mcp.tool() decorator — Pydantic-typed tool registration
• Claude Code integration — .mcp.json auto-discovery + CLAUDE.md

Available Tools

Tool	Description
list_legislators	List legislators with optional filters (term, party, constituency, name)
get_legislator	Get a single legislator by term and name
get_legislator_meets	Get meetings attended by a legislator
get_legislator_propose_bills	Get bills proposed by a legislator
get_legislator_cosign_bills	Get bills co-signed by a legislator
get_legislator_interpellations	Get interpellations where the legislator is the interpellator
list_bills	List bills with optional bill filters
get_bill	Get a single bill by bill number
get_bill_related_bills	Get bills related to a bill
get_bill_doc_html	Get HTML document entries for a bill
get_bill_meets	Get meetings related to a bill
list_meets	List meetings with optional filters
get_meet	Get a single meeting by meeting code
get_meet_ivods	Get IVOD entries related to a meeting
get_meet_bills	Get bills related to a meeting
get_meet_interpellations	Get interpellations related to a meeting
list_interpellations	List interpellations with optional filters
get_interpellation	Get a single interpellation by ID

Usage Examples

"我想查黃國昌委員的基本資料"

You: 幫我查第 11 屆黃國昌委員的資料

AI calls:

get_legislator(
  term = 11,
  name = "黃國昌",
)

Result: SUCCESS — 黃國昌，男，台灣民眾黨，全國不分區及僑居國外國民。學歷：臺灣大學法律系學士、美國康乃爾大學法學博士。曾任中央研究院法律學研究所研究員。已於 2026/02/01 辭職離職。

---

"上禮拜的院會在討論什麼？"

You: 上禮拜院會有開什麼會？討論了哪些事情？

AI calls:

get_meet(
  meet_id = "院會-11-5-5",
)

Result: SUCCESS — 第 11 屆第 5 會期第 5 次會議，日期：2026-03-27、2026-03-31、2026-04-07。議程包含：台灣民眾黨黨團提案要求行政院核准新興民生計畫預算 718 億元，以及對行政院院長施政方針繼續質詢。出席委員共 113 人。

---

"查一下這個議案的內容"

You: 幫我查議案編號 202110200590000 的詳細內容

AI calls:

get_bill(
  bill_no = "202110200590000",
)

Result: SUCCESS — 「衛生福利部組織法第二條、第五條及第八條條文修正草案」，提案委員沈發惠等 18 人。提案日期 2026-03-27，目前狀態：排入院會。案由：因應超高齡社會長照需求、少子女化兒少保護，及全民健保政策權責分工，修正衛福部組織法。

---

"這個議案有沒有相關的其他議案？"

You: 議案 202110200590000 有什麼相關議案？

AI calls:

get_bill_related_bills(
  bill_no = "202110200590000",
)

Result: SUCCESS — 找到相關議案：202110189540000「衛生福利部組織法第二條條文修正草案」，由范雲等 18 人提案（2026-01-30），目前狀態：交付審查。內容聚焦於強化婦女福利業務之專責層級。

---

"羅智強委員有什麼質詢紀錄？"

You: 幫我查羅智強在第 11 屆第 1 會期第 1 次會議的質詢

AI calls:

get_interpellation(
  interpellation_id = "11-1-1-1",
)

Result: SUCCESS — 質詢委員：羅智強，刊登日期 2024-02-16。事由：就文化部發放文化成年禮金政策屢傳遭濫用亂象，未達政策預期效果，向行政院提出質詢。質詢內容涉及文化幣被用於購買非文化類商品（化妝品、日用品、3C）、網路轉賣等問題。

---

"蘇巧慧委員是哪個選區的？"

You: 蘇巧慧委員的基本資料，她是哪個黨、哪個選區？

AI calls:

get_legislator(
  term = 11,
  name = "蘇巧慧",
)

Result: SUCCESS — 蘇巧慧，女，民主進步黨，新北市第 5 選舉區。學歷：美國賓州大學法律碩士、台大法律系司法組。經歷：第九屆、第十屆立法委員，現任第 11 屆第 5 會期內政委員會委員。

---

Quick Start

# Run server
uv run python mcp_server.py

# Interactive dev/test (MCP Inspector)
uv run mcp dev mcp_server.py

Claude Code Integration

Add to your Claude Code config via .mcp.json (already included in this repo):

{
  "mcpServers": {
    "mcp-tw-ly": {
      "command": "uv",
      "args": ["run", "python", "mcp_server.py"],
      "cwd": "/path/to/mcp-tw-ly"
    }
  }
}

Project Structure

mcp-tw-ly/
├── app.py                   # FastMCP singleton
├── mcp_server.py            # Entry point (stdio transport)
├── sources/
│   ├── http_source.py       # Base HTTP client with retry
│   └── lyv2_client.py       # Legislative Yuan API v2 client
├── services/
│   └── container.py         # Dependency injection / client factory
└── tools/
    ├── bill.py              # Bill MCP tools
    ├── interpellation.py    # Interpellation MCP tools
    ├── meet.py              # Meet MCP tools
    └── legislator.py        # Legislator MCP tools

Data Source

All data comes from https://v2.ly.govapi.tw — Taiwan Legislative Yuan open data API v2 (govapi.tw). No API key required.

Testing

python tests/test_all_tools.py   # Run all tool E2E tests

License

MIT License — see LICENSE for details.