Nts Bizinfo MCP

韩国OpenData MCP服务器

可在Claude Desktop、Cursor、Windsurf等MCP支持客户端上使用韩国公共数据门户API的模型上下文协议（MCP）服务器。

提供的功能

国税厅运营商注册信息API

• 查询运营商注册状态 (check_business_status：使用商家注册号查询营业状态（继续/停业/停业）、征税类型（最多100件）
• 确认商家注册真伪 (validate_business_registration：通过商家注册号、开业日期、代表姓名等确认真伪（最多100件）

韩国天文研究院特日信息API（get_korean_holidays)

• 公休日查询：法定假日信息，包括替代假日
• 国庆节查询：3.1节、光复节、开天节、韩文节等
• 节日查询：各种纪念日信息
• 24节气查询：立春、惊蛰、春分等24节气信息
• 杂节查询：韩食、端午、七夕等传统节气

预准备：发放API密钥

1.注册公共数据门户网站会员

1. 公共数据门户 连接
2. 注册会员（需要本人认证）

2.申请API使用

国税厅运营商注册信息API

1. 国税厅_运营商注册信息真伪确认及状态查询服务 连接页面
2. 单击“申请使用”按钮
3. 创建使用目的后申请（自动批准）

韩国天文研究院特日信息API

1. 韩国天文研究院_特日情报 连接页面
2. 单击“申请使用”按钮
3. 创建使用目的后申请（自动批准）

请参见：两个API都使用同一公共数据门户帐户的验证密钥。

3.验证密钥

1. 我的页面→数据利用→开放API→开发帐户
2. 常规验证密钥（Decoding） 复制

安装

方法1:npm全局安装（建议）

npm install -g korea-opendata-mcp

方法2：从源构建

git clone https://github.com/yakuda81-cpu/nts-bizinfo-mcp.git
cd nts-bizinfo-mcp
npm install
npm run build

MCP客户端连接

克劳德桌面

claude_desktop_config.json 修改文件：

• 视窗: %APPDATA%\Claude\claude_desktop_config.json
• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json

npm全局安装

{
  "mcpServers": {
    "korea-opendata": {
      "command": "korea-opendata-mcp",
      "env": {
        "DATA_GO_KR_API_KEY": "여기에_본인의_API_인증키_입력"
      }
    }
  }
}

从源构建时

{
  "mcpServers": {
    "korea-opendata": {
      "command": "node",
      "args": ["C:/Users/사용자명/nts-bizinfo-mcp/dist/index.js"],
      "env": {
        "DATA_GO_KR_API_KEY": "여기에_본인의_API_인증키_입력"
      }
    }
  }
}

克劳德代码

claude mcp add korea-opendata -- node /path/to/nts-bizinfo-mcp/dist/index.js

环境变量为 .env 在文件或壳环境中设置：

export DATA_GO_KR_API_KEY="여기에_본인의_API_인증키_입력"

注意: DATA_GO_KR_API_KEY在公共数据门户网站上获得的 常规验证密钥（Decoding） 请输入。

使用示例

在Claude Desktop中，您可以：

查询运营商状态

"1234567890 사업자의 상태를 조회해줘"
"삼성전자 사업자번호 1248100998의 영업상태 확인해줘"

确认运营商的真实身份

"사업자번호 1234567890, 개업일 20200101, 대표자 홍길동으로 진위확인해줘"

公休日/特日查询

"2025년 공휴일 알려줘"
"이번 달 공휴일이 있어?"
"올해 24절기 알려줘"
"2025년 국경일 조회해줘"

提供工具（Tools）

1.检查_业务_状态

通过运营商注册号查询状态

输入： 参数类型必需说明 |---------|------|-----|------| | business_numbers | string\[\]O|运营商注册号码列表（最多100个）

响应信息：

• 运营商状态（继续运营商/停业者/停业者）
• 征税类型（一般征税者/简易征税者/免税经营者等）
• 停业日期（停业时）
• 课税类型转换日期

2.验证_业务_注册

确认运营商属性的真伪

输入： 参数类型必需说明 |---------|------|-----|------| | businesses|object\[\]O|要查看的运营商信息列表| b_nostringO商家注册号码 start_dt string O开业日期（YYYYMMDD） p_nmstringO代表姓名 p_nm2 string---代表姓名2（共同代表） b_nmstring---商号 corp_nostring---法人注册号码 | b_sector/string--|主要工作状态 b_type string---主要项目

3.获取更多假期

查询韩国公休日、国庆日、纪念日、24节气、杂节信息

输入： 参数类型必需说明 |---------|------|-----|------| 要查询的特殊类型| | year | number | O要查询的年份（例如2025） 开始查询的月份（1-12）。如果省略，请查看整个年度| |monthCount|number|-|要查询的月数（默认值：1）|

type选项： 值说明 |---|------| |holidays|公休日（包括替代公休日）| 全国日国庆节（3.1节，光复节，开天节，韩文节） 纪念日 divisionsInfo24节气 SundryDay杂节（韩食、端午、七夕等）

响应信息：

• 又名
• 日期
• 公休日与否

API限制

国税厅运营商注册信息API

• 每次呼叫最多100次
• 每天最多100万件

韩国天文研究院特日信息API

• 每天最多10000件

项目结构

src/
├── types.ts        # 상수, 타입, 인터페이스, 환경변수 검증
├── validation.ts   # MCP 도구 입력 검증
├── nts-api.ts      # 국세청 API 호출 + 결과 포맷팅
├── kasi-api.ts     # 천문연구원 API 호출 + 결과 포맷팅
└── index.ts        # MCP 서버 설정, 도구 핸들러

依赖性方向： index -> validation / nts-api / kasi-api -> types （单向，无循环参照）

保安

• SSRF防御：对于所有fetch请求 redirect: "error" 应用
• 暂停: AbortController 基于30秒超时
• 错误隐匿：stderr日志记录内部错误详细信息，用户返回一般消息
• 验证输入：商家注册号 /^\d{10}$/ 常规表达式，验证year/month/monthCount范围

故障射击

“DATA_GO_KR_API_KEY环境变量未设置”

• MCP客户端设置的 env 确保在部分中正确输入了API密钥
• NTS_API_KEY也支持下位兼容

“国税局API请求失败”/“天文研究院API请求失败”

• 验证API密钥是否正确（使用解码密钥）
• 验证公共数据门户网站上的服务使用申请是否已完成
• 超过每日呼叫限制时，第二天重试

“API返回了XML响应”

• 暂时的API服务器错误。稍后重试

路线图

• \[\]部署npm注册表（npm publish)
• \[\]GitHub Actions CI/CD配置
• \[\]添加单位测试

许可证

MIT许可证

参考资料

• 公共数据门户网站-国税厅_运营商注册信息真伪确认和状态查询服务
• 公共数据门户网站-韩国天文研究院_特日信息
• 模型上下文协议（MCP）