mcp-to-skill-converter

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

Why This Exists

MCP servers are great but load all tool definitions into context at startup. With 20+ tools, that's 30-50k tokens gone 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 used: ~5k tokens (full instructions)
• Executing: 0 tokens (runs externally)

Quick Start

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

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

# 3. Install dependencies
cd skills/github
pip install mcp

# 4. Copy to Claude
cp -r . ~/.claude/skills/github

Done! Claude can now use GitHub tools with minimal context.

What It Does

The converter:

1. Reads your MCP server config
2. Generates a Skill structure with:
   • SKILL.md - Instructions for Claude
   • executor.py - Handles MCP calls dynamically
   • Config files
3. Claude loads metadata only (~100 tokens)
4. Full instructions load when the skill is needed
5. Executor runs MCP tools outside context

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 Example

GitHub MCP server (8 tools):

Works With

Any standard MCP server:

• ✅ @modelcontextprotocol/server-github
• ✅ @modelcontextprotocol/server-slack
• ✅ @modelcontextprotocol/server-filesystem
• ✅ @modelcontextprotocol/server-postgres
• ✅ Your custom MCP servers

When To Use

Use this converter when:

• You have 10+ tools
• Context space is tight
• Most tools won't be used in each conversation
• Tools are independent

Stick with MCP when:

• You have 1-5 tools
• Need complex OAuth flows
• Need persistent connections
• Cross-platform compatibility critical

Best approach: Use both

• MCP for core tools
• Skills for extended toolset

Requirements

pip install mcp

Python 3.8+ required.

How It Works

┌─────────────────────────────────────┐
│ 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          │
└─────────────────────────────────────┘

Examples

Example 1: GitHub Integration

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

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

# Result: GitHub tools accessible with 100 tokens vs 8k

Example 2: Multiple Servers

# Convert multiple 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

Troubleshooting

"mcp package not found"

pip install mcp

"MCP server not responding"

Check your config file:

• Command is correct
• Environment variables set
• Server is accessible

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": {...}}'

Limitations

• Early stage (feedback welcome)
• Requires mcp Python package
• Some complex auth may need adjustments
• Not all MCP servers tested

Contributing

This is a proof of concept. Contributions welcome:

• Test with more MCP servers
• Improve error handling
• Add more examples
• Better documentation

Credits

Inspired by:

• playwright-skill by @lackeyjb
• Anthropic Skills framework
• Model Context Protocol

License

MIT

Learn More

• Detailed writeup
• Anthropic Skills docs
• MCP specification

Status: Functional but early stage
Feedback: Issues and PRs welcome
Questions: Open an issue