# MCP Taiwan Company Registry

[![PyPI version](https://img.shields.io/pypi/v/mcp-tw-company)](https://pypi.org/project/mcp-tw-company/)
[![Python](https://img.shields.io/pypi/pyversions/mcp-tw-company)](https://pypi.org/project/mcp-tw-company/)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
[![MCP](https://img.shields.io/badge/MCP-compatible-blue)](https://modelcontextprotocol.io/)
[![GitHub stars](https://img.shields.io/github/stars/asgard-ai-platform/mcp-tw-company)](https://github.com/asgard-ai-platform/mcp-tw-company/stargazers)
[![GitHub issues](https://img.shields.io/github/issues/asgard-ai-platform/mcp-tw-company)](https://github.com/asgard-ai-platform/mcp-tw-company/issues)
[![GitHub last commit](https://img.shields.io/github/last-commit/asgard-ai-platform/mcp-tw-company)](https://github.com/asgard-ai-platform/mcp-tw-company/commits/main)

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

[繁體中文](README.zh-TW.md)

## 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`](https://docs.astral.sh/uv/)
- No API key required (public open data)

## Installation

### From PyPI

```bash
pip install mcp-tw-company
```

### With uvx (no install needed)

```bash
uvx mcp-tw-company
```

### From source

```bash
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`:

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

### Claude Code

Add to `.mcp.json` in your project:

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

### Cursor

Add to Cursor MCP settings:

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

## Quick Start

```bash
# 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

```bash
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](CONTRIBUTING.md) for development setup and guidelines.

## License

MIT License — see [LICENSE](LICENSE) for details.