Tw Company

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

An MCP server for Taiwan company registry open data, exposing AI-callable tools over Model Context Protocol (MCP). Powered by the Ministry of Economic Affairs GCIS open data endpoints.

繁體中文

Features

• stdio JSON-RPC 2.0 — Standard MCP transport protocol
• @mcp.tool() decorator — Pydantic-typed tool registration
• REST connector — Retry support with exponential backoff
• No-auth public API access — Uses the GCIS open data endpoint directly
• E2E testing — Live API test runner
• 9 registered tools — Company search, directors, business items, branch offices, and more

Prerequisites

• Python 3.14.x
• uv
• No API key required (public open data)

Installation

From PyPI

pip install mcp-tw-company

With uvx (no install needed)

uvx mcp-tw-company

From source

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

Configuration

Claude Desktop

Add to claude_desktop_config.json:

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

Claude Code

Add to .mcp.json in your project:

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

Cursor

Add to Cursor MCP settings:

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

Quick Start

# Setup
uv sync

# Test connection
uv run python scripts/auth/test_connection.py

# Run server
uv run python mcp_server.py

Usage Examples

"Search for companies by name"

You: 幫我查「宏碁」相關的公司

AI calls:

get_company_registrations_by_name_keyword(
  company_name_keyword = "宏碁",
  company_status = "01",
)

Result: SUCCESS — Returns matching company registrations including name, unified business number, capital, representative, and address.

"Look up a specific company by number"

You: 統一編號 89845559 是哪家公司？

AI calls:

get_company_registration_master_by_number(
  business_accounting_no = "89845559",
)

Result: SUCCESS — Returns master registration profile: 森鉅科技材料股份有限公司, capital NT$3B, located in Tainan.

"Find directors and supervisors"

You: 查一下這家公司的董監事名單

AI calls:

get_company_directors_by_number(
  business_accounting_no = "89845559",
)

Result: SUCCESS — Returns 9 directors/supervisors with positions, names, corporate representatives, and shareholding.

"Check what business items a company is registered for"

You: 這家公司的營業項目有哪些？

AI calls:

get_company_registration_with_business_items_by_number(
  business_accounting_no = "89845559",
)

Result: SUCCESS — Returns company profile with 13 registered business items including manufacturing, trading, and construction.

"Determine entity type by number"

You: 統編 00208407 是公司還是商號？

AI calls:

get_registry_entity_type_by_number(
  no = "00208407",
)

Result: SUCCESS — Returns entity classification (company, branch office, or business).

Tools Reference

Tool	Description	Key Parameters
get_company_registrations_by_name_keyword	Search companies by name keyword	company_name_keyword, company_status
get_company_registration_master_by_number	Company master profile	business_accounting_no (8 digits)
get_company_registration_with_business_items_by_number	Company profile with business items	business_accounting_no (8 digits)
get_company_directors_by_number	Directors and supervisors	business_accounting_no (8 digits)
get_company_name_by_number	Company name lookup	business_accounting_no (8 digits)
get_registry_entity_type_by_number	Entity type classification	no (8 digits)
get_branch_offices_by_company_number	Branch offices by company	business_accounting_no (8 digits)
get_business_registration_profile_by_agency	Business profile by agency	president_no, agency
get_business_registration_items_by_number	Business registration items	president_no (8 digits)

All tools support skip (default 0) and top (default 50) pagination parameters.

TODO

• Integrate company registration basic data (application 2) from F05D1060-7D57-4763-BDCE-0DAF5975AFE0
• Integrate business name by number from 855A3C87-003A-4930-AA4B-2F4130D713DC
• Investigate the upstream access restriction for business registrations by name keyword (A1B4CBFF-2D3A-409B-8A78-2AD94F63AE4A): the test endpoint currently returns unauthorized integration IP in this environment
• Investigate the upstream access restriction for branch offices by branch number (23632BB3-5DB7-4423-9643-1D4AC140D479): the test endpoint currently returns unauthorized integration IP in this environment

Project Structure

mcp-tw-company/
├── app.py                  # FastMCP singleton
├── mcp_server.py           # Entry point (stdio transport)
├── config/settings.py      # API endpoints, URL builder, request headers
├── connectors/
│   └── rest_client.py      #   HTTP REST with retry + pagination
├── auth/
│   └── none.py             #   No auth (public API)
├── tools/
│   └── company_registry_tools.py
├── tests/test_all_tools.py # E2E test runner
└── scripts/auth/test_connection.py

Testing

uv run python scripts/auth/test_connection.py   # Validate API connectivity
uv run python tests/test_all_tools.py           # Run all tool E2E tests

Data Source

This project uses Ministry of Economic Affairs GCIS open data endpoints for company and business registration data.

Contributing

See CONTRIBUTING.md for development setup and guidelines.

License

MIT License — see LICENSE for details.