简体中文 | English

🎮 ExcelMCP: 让游戏策划用嘴说话的Excel神器

🚀 游戏策划必备：用中文/SQL直接操作Excel，告别手动VBA！

🎯 自然语言 → "把技能攻击力全部加10%"
🔧 SQL查询 → "SELECT * FROM skills WHERE class='法师'"
⚡ 智能操作 → 自动跨表JOIN、批量修改、版本管理

🚀 最新更新 (v1.7.19)

🐛 BUG修复

• excel_create_pivot_table修复: Sheet不存在时错误码从OPERATION_FAILED改为SHEET_NOT_FOUND，与其他函数保持一致

📋 验证

• REQ-051验证: 边缘测试脚本函数名正确，无需修改

🎮 游戏场景支持

• 技能系统：CTE查询、平衡分析、批量调整
• 装备管理：套装计算、稀有度分类、评分系统
• 怪物配置：AI行为配置、属性缩放、掉落管理
• 关卡设计：进度统计、难度配置、活动管理

📖 完整更新日志 | 🎯 版本规划

🎯 一句话介绍

"我要把技能攻击力全部加10%,装备按稀有度排序,找出法师职业所有技能"

🎯 不写代码！不学公式！用中文直接命令Excel，智能完成游戏配置管理！

🚀 快速开始(1分钟)

💡 😱 第一次用？ → 先看 🎮 3分钟视频教程
💡 🔥 急用命令？ → 📋 30秒快速参考

🔥 一键安装，即刻使用！

🎯 推荐:uvx(最简单,无安装)

# Mac/Linux 一行命令
curl -LsSf https://astral.sh/uv/install.sh | sh

# Windows PowerShell
powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"

使用:

uvx excel-mcp-server-fastmcp

📦 传统:pip

pip install excel-mcp-server-fastmcp

💡 国内用户:pip install excel-mcp-server-fastmcp -i https://pypi.tuna.tsinghua.edu.cn/simple

🔗 AI 客户端配置(1分钟)

Claude Desktop(推荐)

{
  "mcpServers": {
    "excelmcp": {
      "command": "uvx",
      "args": ["excel-mcp-server-fastmcp"]
    }
  }
}

Cursor

• 设置 → MCP → Add Server
• Name: excelmcp
• Command: uvx
• Args: ["excel-mcp-server-fastmcp"]

其他客户端

• Cherry Studio / VSCode + Continue:同样配置
• OpenClaw:内置支持,无需配置

✅ 验证成功

在 AI 客户端说:"帮我读取技能表测试一下"
看到 Excel 数据?🎉 配置完成!

🚀 3分钟快速开始

🎯 新用户必读（3分钟快速上手）

第一步：准备Excel文件

把你的游戏配置表放到桌面：

~/Desktop/技能表.xlsx
~/Desktop/装备表.xlsx  
~/Desktop/怪物配置表.xlsx

第二步：安装工具（1分钟）

# 安装uv（如果还没安装）
curl -LsSf https://astral.sh/uv/install.sh | sh

# 安装ExcelMCP
uvx excel-mcp-server-fastmcp

第三步：开始使用（1分钟）

打开你常用的AI客户端（Claude Desktop/Cursor/Cherry Studio），配置MCP后，直接说：

# 基础操作
"读取技能表"
"把法师技能攻击力加20%" 
"找出所有史诗装备"

# 进阶操作  
"关联技能表和职业表，统计技能数量"
"分析技能平衡性，找出数值异常的技能"

✅ 成功标志

当你收到类似这样的回复，说明配置成功：

✅ 成功读取技能表
📊 表格信息：3个sheet，127行数据
💡 发现技能数据，可以开始分析...

🎮 游戏开发场景演示 (所见即所得！)

🎯 策划日常工作示例

🎯 真实案例: 以下所有操作都已通过53个游戏专用工具验证
🎮 支持游戏: RPG、MMO、卡牌、塔防、射击、策略等各类游戏
⚡ 性能表现: 支持10万+数据批量处理，响应时间 <1秒

# 🗣️ 用中文直接命令Excel (无需编程!)
"帮我把技能表里所有法师技能攻击力加 20%"
"找出装备表中价格超过 1000 的史诗装备" 
"把技能表和职业表关联,统计每个职业的技能数量"
"复制技能表到新文件,命名为技能备份_v2.xlsx"

🔢 数值策划任务

# 数据分析
"计算每个职业的平均攻击力和防御力"
"找出攻击力最高的前 10 个技能"
"批量调整所有技能冷却时间,乘以 0.8"
"生成角色属性平衡报告"

🏗️ 关卡策划需求

# 关卡配置
"读取关卡配置表,找出所有可收集道具"
"批量修改怪物掉落概率,稀有物品提升 50%"
"生成关卡进度统计报表"

📊 核心功能对比

游戏开发专用对比

优势场景分析

🎮 ExcelMCP 最适合

• 游戏策划:数值调整、配置管理、平衡分析
• 独立开发者:快速原型、配置迭代、多人协作
• 数据分析师:游戏数据分析、用户行为统计
• 运营人员:活动配置、道具管理、版本对比

🔧 传统 Excel 最适合

• 复杂公式计算:财务报表、科学计算
• 可视化图表:动态图表、复杂报表
• 宏自动化:复杂业务流程自动化

💡 ChatGPT 最适合

• 文本处理:文案生成、翻译、总结
• 代码编写:程序开发、算法设计
• 创意内容:游戏设计、故事创作

🐍 Python pandas 最适合

• 大数据处理:百万级行数据处理
• 机器学习:数据建模、算法训练
• 自动化脚本:复杂数据处理流水线

🛠️ 支持的游戏类型

📱 手机端看这里（简化功能对比）

💡 一句话总结：你用自然语言说需求，ExcelMCP帮你搞定Excel操作

💡 使用技巧

🎯 高效指令示例

# 数据分析
"分析技能平衡性,找出伤害过高的技能"
"计算装备套装加成效果,按总价排序"
"统计怪物掉落,找出最值钱的掉落"

# 批量操作
"批量修改所有武器耐久度 +20%"
"复制装备表到不同品质分类"
"生成职业配装推荐"

# 版本管理
"比较技能表新旧版本差异"

🚀 一键复制(即用即改)

技能表分析

"读取技能表,找出所有冷却时间小于3秒的技能,按伤害排序"

装备批量优化

"给所有史诗级装备攻击力+15%,防御+10%"
"找出总评分超过80的装备,按评分降序排列"

怪物AI配置

"修改所有Boss级怪物血量+50%,伤害+30%"
"统计不同类型怪物的平均属性,生成平衡报告"

关卡配置管理

"批量更新关卡难度参数,第5关难度+20%"
"生成各关卡完成率统计报表,标记完成率低于50%的关卡"

🎮 现在试试！3分钟体验ExcelMCP神奇功能

🚀 新手体验（3秒上手！）

# 💡 就这么说就行：
"读取我的技能表，显示前5个技能"
# 🎯 没错！用中文直接命令Excel，就这么简单！

📊 快速分析体验（展示真实力！）

# 🎯 试试这个复杂查询（一条命令搞定）：
"把技能表和职业表关联，找出法师职业所有技能并按攻击力排序"
"分析技能表，找出攻击力最高的3个技能"

🔧 批量操作体验

# 复制这句测试批量修改：
"给所有法师技能的冷却时间减少20%"

🎯 结果对比

• ✅ 成功：看到Excel数据被正确读取和修改
• ❌ 失败：检查Excel文件是否关闭、文件路径是否正确
  "创建配置文件备份"
  "回滚到指定版本"

### 🚀 性能优化
- **大文件**:使用流式写入,支持 10万+ 行数据
- **复杂查询**:自动索引优化,响应 < 3 秒
- **内存占用**:典型文件 < 100MB
- **支持格式**:.xlsx、.xlsm、.xlsb

---

## 📚 文档资源

### 📖 快速上手
- [📋 快速参考指南](docs/QUICK_REFERENCE.md) - 30秒找到你需要命令（新！）
- [互动式教程](docs/INTERACTIVE_TUTORIAL.md) - 分模块游戏配置实战教程（新！）
- [基础教程](docs/README-gaming.md) - 游戏开发入门指南
- [性能优化](docs/README-performance.md) - 大文件处理技巧
- [SQL 参考](docs/README-sql.md) - 高级查询语法

### 🎮 示例代码
- [游戏开发示例](examples/README.md) - 完整技能系统、装备管理案例
- [批量操作示例](examples/进阶操作/) - 数据批处理、版本对比
- [实战案例](examples/实战案例/) - 完整游戏数值平衡方案

---

## 🔧 故障排除

### ❌ 常见问题

**Python 版本问题**
```bash
python --version  # 需要 3.10+
# 升级:https://www.python.org/downloads/

网络问题

# 国内镜像源
pip install -i https://pypi.tuna.tsinghua.edu.cn/simple excel-mcp-server-fastmcp

配置错误

• 检查 JSON 格式是否正确
• 重启 AI 客户端
• 验证 uvx:uvx --version

🆘 获取帮助

# 命令行帮助
excel-mcp-server-fastmcp --help

# 项目文档
https://github.com/TangentDomain/excel-mcp-server

# 提交问题
GitHub Issues → 使用 Bug 报告模板

📈 技术规格

• 响应速度:小文件 < 1秒,大文件 < 5秒
• 数据规模:10万行 × 1000列
• 工具数量:53 个游戏专用工具
• 内存占用:< 100MB(典型文件)
• 支持格式:.xlsx、.xlsm、.xlsb

🤝 参与贡献

🌟 给个 Star 吧!

如果这个工具对你有帮助,请点亮 ⭐ Star

• 🔍 发现工具:帮助更多游戏开发者找到我们
• 🔔 获取更新:Star 后第一时间收到功能更新
• 🎮 推动生态:每一个 Star 都是我们改进的动力

💪 如何贡献

• 🐛 报告 Bug:使用 Issue 模板
• 💡 功能建议:欢迎提出游戏开发新需求
• 📚 改进文档:让其他开发者更容易上手
• 💻 提交代码:查看 贡献指南

📄 许可证

MIT License - 开源友好,可商用

🎉 致谢

感谢所有贡献者和游戏开发者社区!特别感谢:

• 游戏策划和数值策划的宝贵反馈
• 测试用户提供的真实使用场景
• 开发者社区的代码贡献

🔧 常见问题与解决

🚨 90%常见问题（必看）

1. MCP连接失败

问题：AI客户端说"工具不可用"
解决：
1. 检查uv是否安装：uv --version
2. 重新安装：uvx excel-mcp-server-fastmcp --force-reinstall
3. 重启AI客户端

2. Excel文件读取失败

问题：提示"无法打开Excel文件"
解决：
1. 文件路径要完整：/Users/xxx/Desktop/技能表.xlsx（不要~/Desktop）
2. 确认文件是.xlsx格式（不支持.xls/.csv）
3. 文件没有被Excel软件打开

3. 数据格式错误

问题：修改数据后显示异常
解决：
1. 检查是否有合并单元格（建议取消合并）
2. 确保数值列是纯数字，不要混入文本
3. 日期格式要统一（建议用YYYY-MM-DD）

4. 大文件卡顿

问题：10万行以上文件处理慢
解决：
1. 分批处理："先读取前1000行测试"
2. 用WHERE过滤："只处理攻击力>100的技能"
3. 关闭其他占用内存的程序

5. 中文乱码

问题：中文显示为问号或乱码
解决：
1. 确保Excel文件保存为UTF-8编码
2. 检查系统语言设置
3. 使用英文列名避免编码问题

🛠️ 快速自查清单

遇到问题时，按顺序检查：

1. ✅ Excel文件是否关闭？
2. ✅ 文件路径是否完整？
3. ✅ 文件格式是.xlsx？
4. ✅ MCP配置是否正确？
5. ✅ uvx命令是否可用？

💡 快速诊断

大文件处理优化

# 大文件(10万行以上)处理技巧:
"使用流式读取,避免内存溢出"
"分批次处理数据,每次处理1万行"
"关闭Excel自动计算,提升处理速度"

数据格式问题

# 数字变文本问题:
"将文本格式的数字转换为数值格式"
"检查单元格格式,设置为常规或数值"

跨表关联失败

# JOIN查询失败:
"检查关联字段的数据类型是否一致"
"确认关联值在两个表中都存在"
"使用模糊匹配查找可能的不一致"

⚡ 性能优化建议

🎯 最佳实践

• 小文件(<1万行):直接处理,无需特殊优化
• 中文件(1-10万行):启用流式处理,批量操作
• 大文件(>10万行):分块处理,避免全量加载

💾 内存管理

# 大文件处理优化:
"处理后及时清理内存,避免内存泄漏"
"使用分页查询,每次只加载部分数据"
"关闭不必要的Excel功能,减少内存占用"

🔄 批量操作优化

# 高效批量操作:
"批量插入时使用流式写入,性能提升80%"
"批量更新时按行批量,减少IO次数"
"复杂查询先筛选再处理,减少数据量"

🆘 获取帮助

1. 查看日志:检查 .excel_mcp_logs/ 目录下的错误日志
2. 简化问题:先用小文件测试,复现问题后再处理大文件
3. 版本确认:运行 excel-mcp-server-fastmcp --version 确认版本
4. 提交Issue:GitHub Issues

用 AI 重新定义游戏开发配置管理! 🚀