MCP2Skills

🚀 Convert any MCP server into a Claude Skill with 90% context savings.

Why This Exists

MCP servers load all tool definitions into context at startup. With 20+ tools, that’s 30-50k tokens consumed before Claude does any work.

This converter applies the “progressive disclosure” pattern (inspired by playwright-skill) to any MCP server:

• Startup: ~100 tokens (just metadata)
• When needed: ~5k tokens (full instructions)
• Executing: 0 tokens (runs externally)

Quick Start

# 1. Install dependencies
pip install mcp

# 2. Create your MCP config file
cat > my-mcp.json << 'EOF'
{
  "name": "my-service",
  "command": "node",
  "args": ["path/to/mcp-server.js"],
  "env": {"API_TOKEN": "your-token"}
}
EOF

# 3. Convert to Skill
python mcp_to_skill_v2.py \
  --mcp-config my-mcp.json \
  --output-dir ./skills/my-service

# 4. Install to Claude
cp -r skills/my-service ~/.claude/skills/

✅ Done! Your MCP server is now a Claude Skill with minimal context usage.

What It Does

The converter creates an optimized Skill structure:

1. Reads your MCP server config
2. Introspects the MCP server to discover all tools
3. Generates a complete Skill package:
   • SKILL.md - Metadata and full tool documentation
   • executor.py - Dynamic MCP tool executor
   • mcp-config.json - Server configuration
   • package.json - Dependencies
4. Result: Claude loads only ~100 tokens at startup
5. When used: Full instructions (~5k tokens) load on demand
6. Execution: Tools run externally via MCP (0 context tokens)

Context Savings

Before (MCP):

20 tools = 30k tokens always loaded
Context available: 170k / 200k = 85%

After (Skills):

20 skills = 2k tokens metadata
When 1 skill active: 7k tokens
Context available: 193k / 200k = 96.5%

Real Examples

This repository includes working examples in skills/:

DevOps Skill (23 tools)

Complete Youzan DevOps platform integration combining ops-cli and superbus tools.

Context savings:

Example Configs

• example-github-mcp.json - GitHub MCP server template
• opscli-config.json - Ops CLI integration
• superbus-config.json - Deployment bus system

Works With

Any standard MCP server:

• ✅ @modelcontextprotocol/server-github
• ✅ @modelcontextprotocol/server-slack
• ✅ @modelcontextprotocol/server-filesystem
• ✅ @modelcontextprotocol/server-postgres
• ✅ Custom MCP servers (Node.js, Python, etc.)

When To Use

Use this converter when:

• You have 10+ MCP tools
• Context space is limited
• Most tools won’t be used in each conversation
• Tools are independent and don’t need cross-tool coordination

Stick with native MCP when:

• You have 1-5 tools (minimal context overhead)
• Tools need persistent connections or complex state
• Cross-platform compatibility is critical
• You need real-time bidirectional communication

Best Approach: Hybrid

• Keep frequently-used core tools as MCP (always available)
• Convert extended toolsets to Skills (loaded on demand)

Requirements

• Python 3.8+
• mcp package: pip install mcp

How It Works

┌──────────────────────────────────┐
│ MCP Config (JSON)                │
│ - command, args, env             │
└────────────┬─────────────────────┘
             │
             ▼
┌──────────────────────────────────┐
│ mcp_to_skill_v2.py               │
│ - Introspects MCP server         │
│ - Generates optimized structure  │
└────────────┬─────────────────────┘
             │
             ▼
┌──────────────────────────────────┐
│ Generated Skill Package          │
│ ├── SKILL.md (~100 tokens)       │
│ ├── executor.py (dynamic)        │
│ ├── mcp-config.json              │
│ └── package.json                 │
└────────────┬─────────────────────┘
             │
             ▼
┌──────────────────────────────────┐
│ Claude Agent                     │
│ - Loads metadata at startup      │
│ - Loads full docs when needed    │
│ - Executes tools via MCP         │
└──────────────────────────────────┘

Usage Examples

Converting GitHub MCP Server

# 1. Create MCP config
cat > github.json << 'EOF'
{
  "name": "github",
  "command": "npx",
  "args": ["-y", "@modelcontextprotocol/server-github"],
  "env": {"GITHUB_TOKEN": "ghp_your_token"}
}
EOF

# 2. Convert to Skill
python mcp_to_skill_v2.py \
  --mcp-config github.json \
  --output-dir ./skills/github

# 3. Install to Claude
cp -r ./skills/github ~/.claude/skills/

Batch Converting Multiple Servers

# Convert all configs in a directory
for config in configs/*.json; do
  name=$(basename "$config" .json)
  python mcp_to_skill_v2.py \
    --mcp-config "$config" \
    --output-dir "./skills/$name"
done

# Install all to Claude
cp -r ./skills/* ~/.claude/skills/

Troubleshooting

“mcp package not found”

pip install mcp

MCP Server Not Responding

Check your config file:

• Command path is correct (verify with which node, which npx)
• Environment variables are properly set
• Server binary/package is accessible
• Test MCP server directly first

Testing the Generated Skill

cd skills/your-skill

# List tools
python executor.py --list

# Describe a tool
python executor.py --describe tool_name

# Call a tool
python executor.py --call '{"tool": "tool_name", "arguments": {"param": "value"}}'

Limitations & Status

• Early stage - actively seeking feedback
• Requires mcp Python package
• Complex authentication flows may need manual adjustments
• Not all MCP servers have been tested (please report issues!)

Contributing

Contributions welcome! Areas of interest:

• Testing with diverse MCP servers
• Improving error handling and diagnostics
• Adding more real-world examples
• Documentation improvements
• Performance optimizations

Open an issue or submit a PR at github.com/YJGGZHK/MCP2Skills

Credits

This project is based on mcp-to-skill-converter and has been enhanced with additional features and improvements.

Inspired by:

• mcp-to-skill-converter - Original converter implementation
• playwright-skill by @lackeyjb - Progressive disclosure pattern
• Anthropic Claude Skills - Skill framework design
• Model Context Protocol - MCP specification

License

MIT License - See LICENSE file for details

Resources

• MCP Specification
• Claude Skills Documentation
• Example Skills in this repository