MCP to Skill Converter

Convert any MCP (Model Context Protocol) server into a Claude Skill using the progressive disclosure pattern for significant context savings and improved performance.

Context Efficiency Benefits

Traditional MCP approach:

• All tools loaded at startup (10-50k tokens for 20+ tools)
• Context available: 85% of total

Skill approach:

• Metadata only: ~100 tokens at startup
• Full instructions (when used): ~5k tokens
• Tool execution: 0 tokens (runs externally)
• Context available: 96.5% of total

When to Use This Skill

Use this converter when:

• Working with 10+ MCP tools
• Context space is tight
• Most tools are not used in each conversation
• Tools are independent

Stick with direct MCP when:

• Working with 1-5 tools
• Complex OAuth flows are required
• Persistent connections are needed
• Cross-platform compatibility is critical

How It Works

Apply the "progressive disclosure" pattern:

1. Read the MCP server configuration
2. Generate a Skill structure with:
   • SKILL.md - Instructions for Claude
   • executor.py - Handles MCP calls dynamically
   • Config files
3. Load metadata only (~100 tokens)
4. Load full instructions when the skill is needed
5. Run MCP tools through executor outside context

Usage Pattern

Step 1: Create MCP Configuration

Create a JSON configuration file for your MCP server:

{
  "name": "server-name",
  "description": "Server description",
  "command": "npx",
  "args": ["-y", "@modelcontextprotocol/server-name"],
  "env": { "ENV_VAR": "value" }
}

Step 2: Convert to Skill

Execute the converter script:

cd $SKILL_DIR
python scripts/convert_mcp_to_skill.py --mcp-config path/to/config.json --output-dir ./output-dir

Step 3: Install Dependencies

cd ./output-dir
uv pip install mcp

Step 4: Install the Skill

cp -r ./output-dir ~/.claude/skills/skill-name

Available Scripts

convert_mcp_to_skill.py

Transform MCP configurations into skills using this main converter script.

Usage:

python scripts/convert_mcp_to_skill.py --mcp-config CONFIG_FILE --output-dir OUTPUT_DIR

Parameters:

• --mcp-config: Path to MCP server configuration JSON file
• --output-dir: Directory where the generated skill will be created

Example MCP Configurations

Reference assets/examples/ for sample MCP configurations:

• GitHub MCP server
• Slack MCP server
• Filesystem MCP server
• Postgres MCP server

Generated Skill Structure

Generated skills follow this structure:

skill-name/
├── SKILL.md (instructions for Claude)
├── executor.py (handles MCP communication)
├── mcp-config.json (MCP server configuration)
└── package.json (dependencies)

Testing Generated Skills

Test generated skills after conversion:

cd skill-directory

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

Troubleshooting

"mcp package not found"

Install the mcp package:

uv pip install mcp

"MCP server not responding"

Verify the config file:

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

"TypeError: object _AsyncGeneratorContextManager can't be used in 'await' expression"

This error has been fixed in recent versions. The issue occurred with improper async context manager handling.

Solution: Ensure you're using the latest version of the converter:

cd mcp-to-skill
python scripts/convert_mcp_to_skill.py --mcp-config your-config.json --output-dir ./your-skill

For technical details about this fix, see references/async_context_manager_fix.md.

Requirements

• Python 3.8+
• mcp package (install with uv pip install mcp)

References

Reference these files for additional information:

• references/mcp_basics.md - MCP protocol fundamentals
• references/converter_details.md - Technical details about the converter
• references/context_optimization.md - Context optimization strategies

Performance Comparison

Real example with GitHub MCP server (8 tools):

Best Practices

1. Use descriptive names for your skills
2. Include clear descriptions in MCP configurations
3. Test generated skills before deployment
4. Keep MCP configurations in version control
5. Use environment variables for sensitive data

Limitations

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

This skill uses the mcp-to-skill-converter from https://github.com/GBSOSS/-mcp-to-skill-converter