payroll-normalizer-mcp

让任意支持 MCP 的 AI 工具（Claude Code / Claude Desktop / Cursor / Windsurf / Cline / Zed / 支持 MCP 的 ChatGPT 等）都能把五花八门的工资表一键整理成「社保测算标准模板」。

把企业各种格式的工资表（.xlsx/.xls/.csv，多主体多月份）按"自然人跨主体跨月"归并，自动识别列名、把实发换算回应发(税前)，输出 10 列标准模板 + 整理报告。遇到非标表头时，AI 客户端可先 inspect_payroll 看表头样本、判断列含义，再带 overrides 调 normalize_payroll。

工具（MCP tools）

工具	作用
standard_columns	返回标准 10 列定义、身份类型可选值、应发≠实发等口径（映射前先读）
inspect_payroll(folder)	逐文件返回表头、前 3 行样本、自动识别的字段映射、应发口径与问题
normalize_payroll(folder, output_dir?, overrides_json?)	整理为标准模板 xlsx + 报告 md；overrides 修正非标表
generate_blank_template(output_path?)	生成带下拉+说明的空白标准模板

安装：在各家工具里加这个 MCP server

无需先发布到 PyPI——用 uvx 直接从 GitHub 运行（需本机有 uv）。通用配置：

{
  "mcpServers": {
    "payroll-normalizer": {
      "command": "uvx",
      "args": ["--from", "git+https://github.com/dingxiang-me/payroll-normalizer-mcp", "payroll-normalizer-mcp"]
    }
  }
}

放到对应位置即可：

• Claude Code（一条命令）：

  claude mcp add payroll-normalizer -- uvx --from git+https://github.com/dingxiang-me/payroll-normalizer-mcp payroll-normalizer-mcp
  

• Claude Desktop：claude_desktop_config.json → mcpServers（路径见 Settings › Developer）。
• Cursor：项目根 .cursor/mcp.json（或全局 ~/.cursor/mcp.json）→ 同上 mcpServers。
• Windsurf：~/.codeium/windsurf/mcp_config.json → 同上。
• Cline / Zed / 其他：填到各自的 MCP 配置里，command/args 一致。

想更快启动可先发布到 PyPI，再把 args 换成 ["payroll-normalizer-mcp"]。

用法

配置好后，直接对 AI 说：

「把 /path/to/工资表文件夹 里的工资表整理成社保测算标准模板」

AI 会自动调用 inspect_payroll →（必要时）判断非标列 → normalize_payroll，在该文件夹产出 社保测算标准模板_整理结果.xlsx 和 整理报告.md。

依赖

• uv（提供 uvx）
• 运行时自动拉取 mcp、openpyxl；旧版 .xls 另需 xlrd（或先另存为 .xlsx）

配套

产出的标准模板可直接导入「社保公积金薪酬优化测算工具」做测算。本服务只做数据整理，不做社保/个税计算。

许可

MIT