Mcp To Skill Converter

What is Mcp To Skill Converter about?

Mcp To Skill Converter transforms a Model Context Protocol (MCP) server into a Claude Skill. By loading only minimal metadata into the model context and fetching full tool instructions on demand, it reduces the token footprint from tens of thousands to a few hundred, preserving more context for user prompts.

How to use Mcp To Skill Converter?

1. Create an MCP config file (JSON) describing the server you want to convert.

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

2. Run the converter to generate a Claude Skill directory.

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

3. Install the Python MCP package inside the generated skill folder.

   cd skills/github
   pip install mcp
   

4. Copy the skill to Claude's skill location.

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

Claude will now be able to invoke the GitHub tools with only ~100 tokens of metadata loaded initially.

Key features of Mcp To Skill Converter

• Progressive disclosure: loads only metadata at startup (~100 tokens) and full tool docs only when needed.
• Zero‑token execution: actual tool calls run externally via the generated executor.py.
• Universal: works with any standard MCP server (GitHub, Slack, Filesystem, Postgres, custom servers).
• Simple CLI: single‑command conversion with configurable output directory.
• Python‑only runtime: generated skill package requires only the mcp Python library.

Use cases of Mcp To Skill Converter

• Teams with large toolsets (>10 tools) needing to preserve model context for complex reasoning.
• Scenarios where only a subset of tools are used per conversation, avoiding token waste.
• Projects that already use Claude Skills and want to integrate existing MCP servers without rewriting them.
• Rapid prototyping of new tool integrations while keeping token budgets tight.

FAQ from the Mcp To Skill Converter

Q: Do I need to modify my existing MCP server? A: No. The converter reads the server’s JSON config and generates a wrapper; the original server runs unchanged.

Q: What Python version is required? A: Python 3.8 or newer.

Q: Can I convert multiple MCP servers at once? A: Yes. Iterate over your config files and invoke the CLI for each output directory.

Q: How does authentication work? A: Include required env vars (e.g., GITHUB_TOKEN, SLACK_TOKEN) in the MCP config; the generated skill passes them to the executor.

Q: What if a tool needs a persistent connection? A: The converter is best for stateless tools. For persistent connections, consider keeping those tools as native MCP servers.

Q: Is the generated skill compatible with Claude’s latest version? A: The skill follows Claude’s standard Skill layout (SKILL.md, executor.py), so it works with current Claude Skill loading mechanisms.

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):

Metric	MCP	Skill	Savings
Idle	8,000 tokens	100 tokens	98.75%
Active	8,000 tokens	5,000 tokens	37.5%

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