ByteNoteByteNote
字

字节笔记本

2026年2月22日

mcp-to-skill-converter：将 MCP Server 转换为 Claude Skill，节省 90% 上下文

#Skills

本文介绍 mcp-to-skill-converter，一个可以将任何 MCP (Model Context Protocol) server 转换为 Claude Skill 的开源工具。该工具通过"渐进式披露"模式，实现高达 90% 的上下文 token 节省，帮助开发者更高效地使用 Claude Code。

项目简介

mcp-to-skill-converter 是由 GBSOSS 组织开发的开源项目，旨在解决 MCP servers 在启动时加载所有工具定义导致的上下文 token 浪费问题。截至目前，该项目在 GitHub 上已获得 123 stars 和 14 forks，采用 Python 编写，遵循 MIT 许可证。

MCP servers 虽然功能强大，但在启动时会将所有工具定义加载到上下文中。当拥有 20+ 个工具时，这意味着 30-50k 的 token 在 Claude 开始工作之前就被占用了。

核心特性

  • 90% 上下文节省：通过渐进式披露模式大幅减少 token 消耗
  • 兼容所有标准 MCP servers：支持 GitHub、Slack、Filesystem、PostgreSQL 等官方 MCP servers
  • 支持自定义 MCP servers：可处理用户自定义的 MCP 服务器
  • 简单易用：只需一个配置文件即可转换
  • 动态执行：工具在上下文外部运行，零额外 token 消耗

技术栈

  • Python 3.8+：主要开发语言
  • MCP Python 包：用于与 MCP 服务器通信
  • JSON 配置：简单的配置文件格式

安装指南

前置要求

  • Python 3.8 或更高版本
  • pip 包管理器

安装步骤

bash
# 克隆仓库
git clone https://github.com/GBSOSS/-mcp-to-skill-converter.git
cd -mcp-to-skill-converter

# 安装依赖
pip install mcp

快速开始

1. 创建 MCP 配置文件

bash
cat > github-mcp.json << 'EOF'
{
  "name": "github",
  "command": "npx",
  "args": ["-y", "@modelcontextprotocol/server-github"],
  "env": {"GITHUB_TOKEN": "your-token-here"}
}
EOF

2. 转换为 Skill

bash
python mcp_to_skill.py \
  --mcp-config github-mcp.json \
  --output-dir ./skills/github

3. 安装依赖

bash
cd skills/github
pip install mcp

4. 复制到 Claude

bash
cp -r . ~/.claude/skills/github

完成！Claude 现在可以以极少的上下文使用 GitHub 工具。

工作原理

该转换器采用"渐进式披露"模式（受 playwright-skill 启发）：

text
┌─────────────────────────────────────┐
│ Your MCP Config                     │
│ (JSON file)                         │
└──────────┬──────────────────────────┘
           │
           ▼
┌─────────────────────────────────────┐
│ mcp_to_skill.py                     │
│ - Reads config                      │
│ - Generates Skill structure         │
└──────────┬──────────────────────────┘
           │
           ▼
┌─────────────────────────────────────┐
│ Generated Skill                     │
│ ├── SKILL.md (100 tokens)           │
│ ├── executor.py (dynamic calls)     │
│ └── config files                    │
└─────────────────────────────────────┘
           │
           ▼
┌─────────────────────────────────────┐
│ Claude                              │
│ - Loads metadata only               │
│ - Full docs when needed             │
│ - Calls executor for tools          │
└─────────────────────────────────────┘

Token 消耗对比

阶段MCP 模式Skill 模式
启动时~100 tokens (仅元数据)~100 tokens (仅元数据)
使用时~5k tokens (完整说明)~5k tokens (完整说明)
执行时0 tokens (外部运行)0 tokens (外部运行)

上下文节省效果

MCP 模式（转换前）：

text
20 个工具 = 30k tokens 始终加载
可用上下文: 170k / 200k = 85%

Skill 模式（转换后）：

text
20 个 skills = 2k tokens 元数据
当 1 个 skill 激活时: 7k tokens
可用上下文: 193k / 200k = 96.5%

实际案例：GitHub MCP Server

GitHub MCP server（8 个工具）的对比数据：

指标MCPSkill节省率
空闲时8,000 tokens100 tokens98.75%
激活时8,000 tokens5,000 tokens37.5%

使用示例

示例 1：GitHub 集成

bash
# 创建配置
cat > github.json << 'EOF'
{
  "name": "github",
  "command": "npx",
  "args": ["-y", "@modelcontextprotocol/server-github"],
  "env": {"GITHUB_TOKEN": "ghp_your_token"}
}
EOF

# 转换
python mcp_to_skill.py --mcp-config github.json --output-dir ./skills/github

# 结果：GitHub 工具仅需 100 tokens 而非 8k

示例 2：批量转换多个 Servers

bash
# 转换多个 MCP servers
for config in configs/*.json; do
  name=$(basename "$config" .json)
  python mcp_to_skill.py --mcp-config "$config" --output-dir "./skills/$name"
done

测试生成的 Skill

bash
cd skills/your-skill

# 列出工具
python executor.py --list

# 描述工具
python executor.py --describe tool_name

# 调用工具
python executor.py --call '{"tool": "tool_name", "arguments": {...}}'

适用场景

推荐使用转换器的情况

  • 拥有 10+ 个工具
  • 上下文空间有限
  • 大部分工具不会在每个对话中使用
  • 工具之间相互独立

建议继续使用 MCP 的情况

  • 只有 1-5 个工具
  • 需要复杂的 OAuth 流程
  • 需要持久连接
  • 跨平台兼容性至关重要

最佳实践：两者结合使用

  • MCP：用于核心工具
  • Skills：用于扩展工具集

兼容性

支持任何标准 MCP server：

  • ✅ @modelcontextprotocol/server-github
  • ✅ @modelcontextprotocol/server-slack
  • ✅ @modelcontextprotocol/server-filesystem
  • ✅ @modelcontextprotocol/server-postgres
  • ✅ 自定义 MCP servers

故障排除

"mcp package not found"

bash
pip install mcp

"MCP server not responding"

检查配置文件：

  • 命令是否正确
  • 环境变量是否设置
  • 服务器是否可访问

限制

  • 早期阶段项目（欢迎反馈）
  • 需要 mcp Python 包
  • 某些复杂认证可能需要调整
  • 尚未测试所有 MCP servers

贡献

这是一个概念验证项目，欢迎贡献：

  • 测试更多 MCP servers
  • 改进错误处理
  • 添加更多示例
  • 完善文档

相关链接

许可证

MIT License

项目状态：功能完整但处于早期阶段 反馈：欢迎提交 Issues 和 PR 问题：请开 Issue 讨论

Skills
上一篇

SecretaryGPT：浏览器侧边栏的 ChatGPT 私人秘书

下一篇

mcp-to-skill-converter：将 MCP Server 转换为 Claude Skill，节省 90% 上下文

分享: