# NTS Business Verification MCP Server
국세청 사업자등록정보 진위확인 및 상태조회 서비스
## Overview
This MCP server provides access to the NTS (National Tax Service) Business Registration Verification API from Korea's data.go.kr portal through the Model Context Protocol. It allows you to verify business registration information authenticity and check business registration status.
## Installation
### Via PyPI
```bash
pip install data-go-mcp.nts-business-verification
```
### Via UV
```bash
uvx data-go-mcp.nts-business-verification
```
## Configuration
### Getting an API Key
1. Visit [data.go.kr](https://www.data.go.kr)
2. Sign up for an account
3. Search for "국세청_사업자등록정보 진위확인 및 상태조회 서비스" API
4. Apply for API access
5. Get your service key from the API management page
### Environment Setup
Set your API key as an environment variable:
```bash
export NTS_BUSINESS_VERIFICATION_API_KEY="your-api-key-here"
```
### Claude Desktop Configuration
Add to your Claude Desktop configuration file:
**macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json`
**Windows**: `%APPDATA%\Claude\claude_desktop_config.json`
#### Option 1: Install from PyPI (when published)
```json
{
"mcpServers": {
"data-go-mcp.nts-business-verification": {
"command": "uvx",
"args": ["data-go-mcp.nts-business-verification@latest"],
"env": {
"NTS_BUSINESS_VERIFICATION_API_KEY": "your-api-key-here"
}
}
}
}
```
#### Option 2: Local Development Setup
For local development, use the virtual environment Python directly:
```json
{
"mcpServers": {
"nts-business-verification": {
"command": "/path/to/your/project/.venv/bin/python",
"args": [
"-m",
"data_go_mcp.nts_business_verification.server"
],
"cwd": "/path/to/your/project/src/nts-business-verification",
"env": {
"NTS_BUSINESS_VERIFICATION_API_KEY": "your-api-key-here",
"PYTHONPATH": "/path/to/your/project/src/nts-business-verification"
}
}
}
}
```
**Example for macOS:**
```json
{
"mcpServers": {
"nts-business-verification": {
"command": "/Users/username/github/data-go-mcp-servers/.venv/bin/python",
"args": [
"-m",
"data_go_mcp.nts_business_verification.server"
],
"cwd": "/Users/username/github/data-go-mcp-servers/src/nts-business-verification",
"env": {
"NTS_BUSINESS_VERIFICATION_API_KEY": "your-api-key-here",
"PYTHONPATH": "/Users/username/github/data-go-mcp-servers/src/nts-business-verification"
}
}
}
}
```
**Example for Windows:**
```json
{
"mcpServers": {
"nts-business-verification": {
"command": "C:\\Users\\username\\github\\data-go-mcp-servers\\.venv\\Scripts\\python.exe",
"args": [
"-m",
"data_go_mcp.nts_business_verification.server"
],
"cwd": "C:\\Users\\username\\github\\data-go-mcp-servers\\src\\nts-business-verification",
"env": {
"NTS_BUSINESS_VERIFICATION_API_KEY": "your-api-key-here",
"PYTHONPATH": "C:\\Users\\username\\github\\data-go-mcp-servers\\src\\nts-business-verification"
}
}
}
}
```
**Important Notes:**
- Replace `/path/to/your/project` or `username` with your actual paths
- After saving the configuration, completely quit and restart Claude Desktop
- The MCP server indicator will appear in the bottom-right corner of the conversation input box when successfully connected
## Available Tools
### validate_business
Validate business registration information authenticity.
**Parameters:**
- `business_number` (str, required): Business registration number (10 digits, hyphens auto-removed)
- `start_date` (str, required): Business start date (YYYYMMDD or YYYY-MM-DD format)
- `representative_name` (str, required): Representative name
- `representative_name2` (str, optional): Representative name 2 (for foreigners, Korean name)
- `business_name` (str, optional): Business name
- `corp_number` (str, optional): Corporation registration number (13 digits)
- `business_sector` (str, optional): Main business sector
- `business_type` (str, optional): Main business type
- `business_address` (str, optional): Business address
**Returns:**
- `business_number`: Business registration number
- `valid`: Validation result ("01": match, "02": no match)
- `valid_msg`: Validation message
- `status`: Business status information (if matched)
**Example:**
```python
result = await validate_business(
business_number="123-45-67890",
start_date="2020-01-01",
representative_name="홍길동",
business_name="테스트회사"
)
```
### check_business_status
Check business registration status for one or more businesses.
**Parameters:**
- `business_numbers` (str, required): Comma-separated business registration numbers (max 100)
**Returns:**
- `request_count`: Number of requested items
- `match_count`: Number of matched items
- `businesses`: List of business status information
**Example:**
```python
result = await check_business_status("1234567890,0987654321")
```
### batch_validate_businesses
Batch validate multiple business registration information at once.
**Parameters:**
- `businesses_json` (str, required): JSON string containing array of business information (max 100)
**Required fields in each business object:**
- `b_no`: Business registration number
- `start_dt`: Business start date
- `p_nm`: Representative name
**Optional fields:**
- `p_nm2`: Representative name 2
- `b_nm`: Business name
- `corp_no`: Corporation registration number
- `b_sector`: Main business sector
- `b_type`: Main business type
- `b_adr`: Business address
**Returns:**
- `request_count`: Number of requested items
- `valid_count`: Number of valid items
- `results`: List of validation results
**Example:**
```python
businesses_json = '''[
{
"b_no": "1234567890",
"start_dt": "20200101",
"p_nm": "홍길동",
"b_nm": "테스트회사"
},
{
"b_no": "0987654321",
"start_dt": "20210101",
"p_nm": "김철수"
}
]'''
result = await batch_validate_businesses(businesses_json)
```
## Business Status Codes
### Business Status (`b_stt_cd`)
- `01`: 계속사업자 (Active business)
- `02`: 휴업자 (Suspended business)
- `03`: 폐업자 (Closed business)
### Tax Type Codes (`tax_type_cd`)
- `01`: 부가가치세 일반과세자 (VAT general taxpayer)
- `02`: 부가가치세 간이과세자 (VAT simplified taxpayer)
- Other codes may apply depending on tax status
## Development
### Setup
```bash
# Clone the repository
git clone https://github.com/Koomook/data-go-mcp-servers.git
cd data-go-mcp-servers/src/nts-business-verification
# Install dependencies
uv sync
```
### Testing
```bash
# Run tests
uv run pytest tests/
# Run with coverage
uv run pytest tests/ --cov=data_go_mcp.nts_business_verification
```
### Running Locally
```bash
# Set your API key
export NTS_BUSINESS_VERIFICATION_API_KEY="your-api-key"
# Run the server
uv run python -m data_go_mcp.nts_business_verification.server
```
## API Documentation
For detailed API documentation, visit: https://api.odcloud.kr/api/nts-businessman/v1
## Error Codes
- `BAD_JSON_REQUEST`: Invalid JSON format in request
- `REQUEST_DATA_MALFORMED`: Required parameters missing
- `TOO_LARGE_REQUEST`: More than 100 items requested
- `INTERNAL_ERROR`: Server internal error
- `HTTP_ERROR`: HTTP communication error
## License
Apache License 2.0
## Contributing
Contributions are welcome! Please see the [main repository](https://github.com/Koomook/data-go-mcp-servers) for contribution guidelines.
Raw data
{
"_id": null,
"home_page": null,
"name": "data-go-mcp.nts-business-verification",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.10",
"maintainer_email": null,
"keywords": "api, data.go.kr, korea, mcp, nts-business-verification",
"author": null,
"author_email": "Your Name <your.email@example.com>",
"download_url": "https://files.pythonhosted.org/packages/30/d3/c260a9a03e57a852835431f35bd52f798f21fec75ae37d5e3338d29119ea/data_go_mcp_nts_business_verification-0.1.0.tar.gz",
"platform": null,
"description": "# NTS Business Verification MCP Server\n\n\uad6d\uc138\uccad \uc0ac\uc5c5\uc790\ub4f1\ub85d\uc815\ubcf4 \uc9c4\uc704\ud655\uc778 \ubc0f \uc0c1\ud0dc\uc870\ud68c \uc11c\ube44\uc2a4\n\n## Overview\n\nThis MCP server provides access to the NTS (National Tax Service) Business Registration Verification API from Korea's data.go.kr portal through the Model Context Protocol. It allows you to verify business registration information authenticity and check business registration status.\n\n## Installation\n\n### Via PyPI\n\n```bash\npip install data-go-mcp.nts-business-verification\n```\n\n### Via UV\n\n```bash\nuvx data-go-mcp.nts-business-verification\n```\n\n## Configuration\n\n### Getting an API Key\n\n1. Visit [data.go.kr](https://www.data.go.kr)\n2. Sign up for an account\n3. Search for \"\uad6d\uc138\uccad_\uc0ac\uc5c5\uc790\ub4f1\ub85d\uc815\ubcf4 \uc9c4\uc704\ud655\uc778 \ubc0f \uc0c1\ud0dc\uc870\ud68c \uc11c\ube44\uc2a4\" API\n4. Apply for API access\n5. Get your service key from the API management page\n\n### Environment Setup\n\nSet your API key as an environment variable:\n\n```bash\nexport NTS_BUSINESS_VERIFICATION_API_KEY=\"your-api-key-here\"\n```\n\n### Claude Desktop Configuration\n\nAdd to your Claude Desktop configuration file:\n\n**macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json` \n**Windows**: `%APPDATA%\\Claude\\claude_desktop_config.json`\n\n#### Option 1: Install from PyPI (when published)\n\n```json\n{\n \"mcpServers\": {\n \"data-go-mcp.nts-business-verification\": {\n \"command\": \"uvx\",\n \"args\": [\"data-go-mcp.nts-business-verification@latest\"],\n \"env\": {\n \"NTS_BUSINESS_VERIFICATION_API_KEY\": \"your-api-key-here\"\n }\n }\n }\n}\n```\n\n#### Option 2: Local Development Setup\n\nFor local development, use the virtual environment Python directly:\n\n```json\n{\n \"mcpServers\": {\n \"nts-business-verification\": {\n \"command\": \"/path/to/your/project/.venv/bin/python\",\n \"args\": [\n \"-m\",\n \"data_go_mcp.nts_business_verification.server\"\n ],\n \"cwd\": \"/path/to/your/project/src/nts-business-verification\",\n \"env\": {\n \"NTS_BUSINESS_VERIFICATION_API_KEY\": \"your-api-key-here\",\n \"PYTHONPATH\": \"/path/to/your/project/src/nts-business-verification\"\n }\n }\n }\n}\n```\n\n**Example for macOS:**\n```json\n{\n \"mcpServers\": {\n \"nts-business-verification\": {\n \"command\": \"/Users/username/github/data-go-mcp-servers/.venv/bin/python\",\n \"args\": [\n \"-m\",\n \"data_go_mcp.nts_business_verification.server\"\n ],\n \"cwd\": \"/Users/username/github/data-go-mcp-servers/src/nts-business-verification\",\n \"env\": {\n \"NTS_BUSINESS_VERIFICATION_API_KEY\": \"your-api-key-here\",\n \"PYTHONPATH\": \"/Users/username/github/data-go-mcp-servers/src/nts-business-verification\"\n }\n }\n }\n}\n```\n\n**Example for Windows:**\n```json\n{\n \"mcpServers\": {\n \"nts-business-verification\": {\n \"command\": \"C:\\\\Users\\\\username\\\\github\\\\data-go-mcp-servers\\\\.venv\\\\Scripts\\\\python.exe\",\n \"args\": [\n \"-m\",\n \"data_go_mcp.nts_business_verification.server\"\n ],\n \"cwd\": \"C:\\\\Users\\\\username\\\\github\\\\data-go-mcp-servers\\\\src\\\\nts-business-verification\",\n \"env\": {\n \"NTS_BUSINESS_VERIFICATION_API_KEY\": \"your-api-key-here\",\n \"PYTHONPATH\": \"C:\\\\Users\\\\username\\\\github\\\\data-go-mcp-servers\\\\src\\\\nts-business-verification\"\n }\n }\n }\n}\n```\n\n**Important Notes:**\n- Replace `/path/to/your/project` or `username` with your actual paths\n- After saving the configuration, completely quit and restart Claude Desktop\n- The MCP server indicator will appear in the bottom-right corner of the conversation input box when successfully connected\n\n## Available Tools\n\n### validate_business\n\nValidate business registration information authenticity.\n\n**Parameters:**\n- `business_number` (str, required): Business registration number (10 digits, hyphens auto-removed)\n- `start_date` (str, required): Business start date (YYYYMMDD or YYYY-MM-DD format)\n- `representative_name` (str, required): Representative name\n- `representative_name2` (str, optional): Representative name 2 (for foreigners, Korean name)\n- `business_name` (str, optional): Business name\n- `corp_number` (str, optional): Corporation registration number (13 digits)\n- `business_sector` (str, optional): Main business sector\n- `business_type` (str, optional): Main business type\n- `business_address` (str, optional): Business address\n\n**Returns:**\n- `business_number`: Business registration number\n- `valid`: Validation result (\"01\": match, \"02\": no match)\n- `valid_msg`: Validation message\n- `status`: Business status information (if matched)\n\n**Example:**\n```python\nresult = await validate_business(\n business_number=\"123-45-67890\",\n start_date=\"2020-01-01\",\n representative_name=\"\ud64d\uae38\ub3d9\",\n business_name=\"\ud14c\uc2a4\ud2b8\ud68c\uc0ac\"\n)\n```\n\n### check_business_status\n\nCheck business registration status for one or more businesses.\n\n**Parameters:**\n- `business_numbers` (str, required): Comma-separated business registration numbers (max 100)\n\n**Returns:**\n- `request_count`: Number of requested items\n- `match_count`: Number of matched items\n- `businesses`: List of business status information\n\n**Example:**\n```python\nresult = await check_business_status(\"1234567890,0987654321\")\n```\n\n### batch_validate_businesses\n\nBatch validate multiple business registration information at once.\n\n**Parameters:**\n- `businesses_json` (str, required): JSON string containing array of business information (max 100)\n\n**Required fields in each business object:**\n- `b_no`: Business registration number\n- `start_dt`: Business start date\n- `p_nm`: Representative name\n\n**Optional fields:**\n- `p_nm2`: Representative name 2\n- `b_nm`: Business name\n- `corp_no`: Corporation registration number\n- `b_sector`: Main business sector\n- `b_type`: Main business type\n- `b_adr`: Business address\n\n**Returns:**\n- `request_count`: Number of requested items\n- `valid_count`: Number of valid items\n- `results`: List of validation results\n\n**Example:**\n```python\nbusinesses_json = '''[\n {\n \"b_no\": \"1234567890\",\n \"start_dt\": \"20200101\",\n \"p_nm\": \"\ud64d\uae38\ub3d9\",\n \"b_nm\": \"\ud14c\uc2a4\ud2b8\ud68c\uc0ac\"\n },\n {\n \"b_no\": \"0987654321\",\n \"start_dt\": \"20210101\",\n \"p_nm\": \"\uae40\ucca0\uc218\"\n }\n]'''\n\nresult = await batch_validate_businesses(businesses_json)\n```\n\n## Business Status Codes\n\n### Business Status (`b_stt_cd`)\n- `01`: \uacc4\uc18d\uc0ac\uc5c5\uc790 (Active business)\n- `02`: \ud734\uc5c5\uc790 (Suspended business)\n- `03`: \ud3d0\uc5c5\uc790 (Closed business)\n\n### Tax Type Codes (`tax_type_cd`)\n- `01`: \ubd80\uac00\uac00\uce58\uc138 \uc77c\ubc18\uacfc\uc138\uc790 (VAT general taxpayer)\n- `02`: \ubd80\uac00\uac00\uce58\uc138 \uac04\uc774\uacfc\uc138\uc790 (VAT simplified taxpayer)\n- Other codes may apply depending on tax status\n\n## Development\n\n### Setup\n\n```bash\n# Clone the repository\ngit clone https://github.com/Koomook/data-go-mcp-servers.git\ncd data-go-mcp-servers/src/nts-business-verification\n\n# Install dependencies\nuv sync\n```\n\n### Testing\n\n```bash\n# Run tests\nuv run pytest tests/\n\n# Run with coverage\nuv run pytest tests/ --cov=data_go_mcp.nts_business_verification\n```\n\n### Running Locally\n\n```bash\n# Set your API key\nexport NTS_BUSINESS_VERIFICATION_API_KEY=\"your-api-key\"\n\n# Run the server\nuv run python -m data_go_mcp.nts_business_verification.server\n```\n\n## API Documentation\n\nFor detailed API documentation, visit: https://api.odcloud.kr/api/nts-businessman/v1\n\n## Error Codes\n\n- `BAD_JSON_REQUEST`: Invalid JSON format in request\n- `REQUEST_DATA_MALFORMED`: Required parameters missing\n- `TOO_LARGE_REQUEST`: More than 100 items requested\n- `INTERNAL_ERROR`: Server internal error\n- `HTTP_ERROR`: HTTP communication error\n\n## License\n\nApache License 2.0\n\n## Contributing\n\nContributions are welcome! Please see the [main repository](https://github.com/Koomook/data-go-mcp-servers) for contribution guidelines.",
"bugtrack_url": null,
"license": "Apache-2.0",
"summary": "MCP server for \uad6d\uc138\uccad \uc0ac\uc5c5\uc790\ub4f1\ub85d\uc815\ubcf4 \uc9c4\uc704\ud655\uc778 \ubc0f \uc0c1\ud0dc\uc870\ud68c \uc11c\ube44\uc2a4",
"version": "0.1.0",
"project_urls": {
"Bug Tracker": "https://github.com/Koomook/data-go-mcp-servers/issues",
"Changelog": "https://github.com/Koomook/data-go-mcp-servers/blob/main/src/nts-business-verification/CHANGELOG.md",
"Documentation": "https://github.com/Koomook/data-go-mcp-servers/tree/main/src/nts-business-verification",
"Homepage": "https://github.com/Koomook/data-go-mcp-servers",
"Repository": "https://github.com/Koomook/data-go-mcp-servers"
},
"split_keywords": [
"api",
" data.go.kr",
" korea",
" mcp",
" nts-business-verification"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "e5b67b09bee117025f389775bc5b13c73a68cf972ed160d89f2e8dc4795e7dcc",
"md5": "a80637d2cbfe516384f29676ce3f9b9e",
"sha256": "760108ff2b7549652ddf26aaa4ea88eb8e6f64390070650063309e89d7d8764a"
},
"downloads": -1,
"filename": "data_go_mcp_nts_business_verification-0.1.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "a80637d2cbfe516384f29676ce3f9b9e",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.10",
"size": 11664,
"upload_time": "2025-08-28T10:27:52",
"upload_time_iso_8601": "2025-08-28T10:27:52.953838Z",
"url": "https://files.pythonhosted.org/packages/e5/b6/7b09bee117025f389775bc5b13c73a68cf972ed160d89f2e8dc4795e7dcc/data_go_mcp_nts_business_verification-0.1.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "30d3c260a9a03e57a852835431f35bd52f798f21fec75ae37d5e3338d29119ea",
"md5": "0607b0080a46b148939e23d68fc3a9dc",
"sha256": "20c952b600f8bcbc790046142211e32a95ea86e5ea5e9ce18116ee378d26fc2c"
},
"downloads": -1,
"filename": "data_go_mcp_nts_business_verification-0.1.0.tar.gz",
"has_sig": false,
"md5_digest": "0607b0080a46b148939e23d68fc3a9dc",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.10",
"size": 12014,
"upload_time": "2025-08-28T10:27:55",
"upload_time_iso_8601": "2025-08-28T10:27:55.166560Z",
"url": "https://files.pythonhosted.org/packages/30/d3/c260a9a03e57a852835431f35bd52f798f21fec75ae37d5e3338d29119ea/data_go_mcp_nts_business_verification-0.1.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-08-28 10:27:55",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "Koomook",
"github_project": "data-go-mcp-servers",
"travis_ci": false,
"coveralls": false,
"github_actions": false,
"lcname": "data-go-mcp.nts-business-verification"
}
JSON
