Skip to content
Back to search

-mcp-to-skill-converter

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

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today
Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/gbsoss--mcp-to-skill-converter/badge.svg)](/listings/gbsoss--mcp-to-skill-converter)

HTML

<a href="/listings/gbsoss--mcp-to-skill-converter"><img src="/api/listings/gbsoss--mcp-to-skill-converter/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

# 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 was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

README.md · README · 239 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

  1. # mcp-to-skill-converter
  2. Convert any MCP server into a Claude Skill with 90% context savings.
  3. ## Why This Exists
  4. 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.
  5. This converter applies the "progressive disclosure" pattern (inspired by playwright-skill) to any MCP server:
  6. - **Startup**: ~100 tokens (just metadata)
  7. - **When used**: ~5k tokens (full instructions)
  8. - **Executing**: 0 tokens (runs externally)
  9. ## Quick Start
  10. ```bash
  11. # 1. Create your MCP config file
  12. cat > github-mcp.json << 'EOF'
  13. {
  14. "name": "github",
  15. "command": "npx",
  16. "args": ["-y", "@modelcontextprotocol/server-github"],
  17. "env": {"GITHUB_TOKEN": "your-token-here"}
  18. }
  19. EOF
  20. # 2. Convert to Skill
  21. python mcp_to_skill.py \
  22. --mcp-config github-mcp.json \
  23. --output-dir ./skills/github
  24. # 3. Install dependencies
  25. cd skills/github
  26. pip install mcp
  27. # 4. Copy to Claude
  28. cp -r . ~/.claude/skills/github
  29. ```
  30. Done! Claude can now use GitHub tools with minimal context.
  31. ## What It Does
  32. The converter:
  33. 1. Reads your MCP server config
  34. 2. Generates a Skill structure with:
  35. - `SKILL.md` - Instructions for Claude
  36. - `executor.py` - Handles MCP calls dynamically
  37. - Config files
  38. 3. Claude loads metadata only (~100 tokens)
  39. 4. Full instructions load when the skill is needed
  40. 5. Executor runs MCP tools outside context
  41. ## Context Savings
  42. **Before (MCP)**:
  43. ```
  44. 20 tools = 30k tokens always loaded
  45. Context available: 170k / 200k = 85%
  46. ```
  47. **After (Skills)**:
  48. ```
  49. 20 skills = 2k tokens metadata
  50. When 1 skill active: 7k tokens
  51. Context available: 193k / 200k = 96.5%
  52. ```
  53. ## Real Example
  54. GitHub MCP server (8 tools):
  55. | Metric | MCP | Skill | Savings |
  56. |--------|-----|-------|---------|
  57. | Idle | 8,000 tokens | 100 tokens | 98.75% |
  58. | Active | 8,000 tokens | 5,000 tokens | 37.5% |
  59. ## Works With
  60. Any standard MCP server:
  61. - ✅ @modelcontextprotocol/server-github
  62. - ✅ @modelcontextprotocol/server-slack
  63. - ✅ @modelcontextprotocol/server-filesystem
  64. - ✅ @modelcontextprotocol/server-postgres
  65. - ✅ Your custom MCP servers
  66. ## When To Use
  67. **Use this converter when:**
  68. - You have 10+ tools
  69. - Context space is tight
  70. - Most tools won't be used in each conversation
  71. - Tools are independent
  72. **Stick with MCP when:**
  73. - You have 1-5 tools
  74. - Need complex OAuth flows
  75. - Need persistent connections
  76. - Cross-platform compatibility critical
  77. **Best approach: Use both**
  78. - MCP for core tools
  79. - Skills for extended toolset
  80. ## Requirements
  81. ```bash
  82. pip install mcp
  83. ```
  84. Python 3.8+ required.
  85. ## How It Works
  86. ```
  87. ┌─────────────────────────────────────┐
  88. │ Your MCP Config │
  89. │ (JSON file) │
  90. └──────────┬──────────────────────────┘
  91. │
  92. ▼
  93. ┌─────────────────────────────────────┐
  94. │ mcp_to_skill.py │
  95. │ - Reads config │
  96. │ - Generates Skill structure │
  97. └──────────┬──────────────────────────┘
  98. │
  99. ▼
  100. ┌─────────────────────────────────────┐
  101. │ Generated Skill │
  102. │ ├── SKILL.md (100 tokens) │
  103. │ ├── executor.py (dynamic calls) │
  104. │ └── config files │
  105. └─────────────────────────────────────┘
  106. │
  107. ▼
  108. ┌─────────────────────────────────────┐
  109. │ Claude │
  110. │ - Loads metadata only │
  111. │ - Full docs when needed │
  112. │ - Calls executor for tools │
  113. └─────────────────────────────────────┘
  114. ```
  115. ## Examples
  116. ### Example 1: GitHub Integration
  117. ```bash
  118. # Create config
  119. cat > github.json << 'EOF'
  120. {
  121. "name": "github",
  122. "command": "npx",
  123. "args": ["-y", "@modelcontextprotocol/server-github"],
  124. "env": {"GITHUB_TOKEN": "ghp_your_token"}
  125. }
  126. EOF
  127. # Convert
  128. python mcp_to_skill.py --mcp-config github.json --output-dir ./skills/github
  129. # Result: GitHub tools accessible with 100 tokens vs 8k
  130. ```
  131. ### Example 2: Multiple Servers
  132. ```bash
  133. # Convert multiple MCP servers
  134. for config in configs/*.json; do
  135. name=$(basename "$config" .json)
  136. python mcp_to_skill.py --mcp-config "$config" --output-dir "./skills/$name"
  137. done
  138. ```
  139. ## Troubleshooting
  140. ### "mcp package not found"
  141. ```bash
  142. pip install mcp
  143. ```
  144. ### "MCP server not responding"
  145. Check your config file:
  146. - Command is correct
  147. - Environment variables set
  148. - Server is accessible
  149. ### Testing the generated skill
  150. ```bash
  151. cd skills/your-skill
  152. # List tools
  153. python executor.py --list
  154. # Describe a tool
  155. python executor.py --describe tool_name
  156. # Call a tool
  157. python executor.py --call '{"tool": "tool_name", "arguments": {...}}'
  158. ```
  159. ## Limitations
  160. - Early stage (feedback welcome)
  161. - Requires `mcp` Python package
  162. - Some complex auth may need adjustments
  163. - Not all MCP servers tested
  164. ## Contributing
  165. This is a proof of concept. Contributions welcome:
  166. - Test with more MCP servers
  167. - Improve error handling
  168. - Add more examples
  169. - Better documentation
  170. ## Credits
  171. Inspired by:
  172. - [playwright-skill](https://github.com/lackeyjb/playwright-skill) by @lackeyjb
  173. - [Anthropic Skills](https://www.anthropic.com/news/skills) framework
  174. - [Model Context Protocol](https://modelcontextprotocol.io/)
  175. ## License
  176. MIT
  177. ## Learn More
  178. - [Detailed writeup](link-to-your-gist)
  179. - [Anthropic Skills docs](https://www.anthropic.com/news/skills)
  180. - [MCP specification](https://modelcontextprotocol.io/)
  181. ---
  182. **Status**: Functional but early stage
  183. **Feedback**: Issues and PRs welcome
  184. **Questions**: Open an issue

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.