MCP to Claude Skills Converter

Problem

I had a dozen MCP servers configured in Claude Desktop. Useful things: filesystem tools, search, database connectors. But when I switched to Claude Code, none of them worked. Claude Code uses skills, not MCP configs. To get the same capability back, I had to read each server’s source, understand its tool definitions, write wrapper scripts, and author a SKILL.md manifest — for every single server.

I did it once. It took about forty minutes. I did not want to do it twelve more times.

The MCP ecosystem had grown fast, but the bridge to skill-based workflows didn’t exist. The gap wasn’t philosophical — it was mechanical. The information needed to generate a skill was all there in the package registry and source code. Someone just needed to extract it automatically.

Approach

I designed mcp-to-skills as an intelligent automation tool that eliminates the manual conversion process entirely. The architecture centers around three core components: intelligent source fetching, AI-powered analysis, and automated skill generation.

The tool automatically detects MCP server configurations from standard locations across macOS and Linux systems, supporting both Claude Desktop’s nested format and flat configuration schemas. For source analysis, I integrated with package registries (npm and PyPI) to fetch server source code dynamically, then leverage Claude’s API to intelligently extract tool definitions, parameters, and documentation.

Key Design Elements

• Multi-registry package fetching with npm and PyPI support for comprehensive MCP server coverage
• AI-powered source analysis using Claude to understand complex codebases and extract tool definitions
• PEP 723 compliant wrapper generation creating self-contained Python scripts that work seamlessly with uv run
• Cross-platform configuration detection supporting Claude Desktop and custom config file formats
• Flexible output targeting with support for Claude Code, Cursor, and custom directory structures
• Environment variable inheritance preserving MCP server environment requirements in generated skills

What It Produces

Running the converter against an MCP server looks like this:

$ mcp-to-skills convert @modelcontextprotocol/server-filesystem

Fetching source from npm registry...
Analyzing tool definitions with Claude...
Generating skill files...

✓ Created: ~/.claude/skills/filesystem/SKILL.md
✓ Created: ~/.claude/skills/filesystem/run.py

The generated SKILL.md contains tool names, parameter schemas, and usage examples pulled directly from the server source. The run.py wrapper is PEP 723 compliant, so uv run run.py list_directory --path /tmp just works without a separate install step.

The output isn’t perfect on the first pass for every server — Claude’s extraction is good, but unusual MCP schemas occasionally need a manual touch-up. That’s an acceptable tradeoff for avoiding forty minutes of hand-authoring.

What I Learned

The hard part wasn’t the AI analysis — it was the source fetching. npm packages are straightforward, but PyPI distributions package things inconsistently: sometimes the source is bundled, sometimes it’s a compiled extension, sometimes the relevant tool definitions live three levels deep in a module I had to trace manually before I could teach Claude to find it automatically.

The second lesson: generated skills need a review pass, not a trust pass. I built a --dry-run flag early specifically because I wanted to inspect what was generated before writing files. That flag gets used more than any other option.

PEP 723 was the right call for wrapper scripts. Self-contained scripts with inline dependency declarations are exactly what you want for something that needs to run reliably across machines without a dedicated virtualenv.

Key Contributions

• Implemented intelligent package registry integration to automatically fetch source code from npm and PyPI based on MCP server commands
• Designed AI-powered source analysis system using Claude API to extract tool definitions, parameters, and documentation from complex codebases
• Built comprehensive skill generation engine that creates SKILL.md manifests and PEP 723 compliant Python wrapper scripts
• Developed flexible configuration detection supporting multiple config formats and auto-discovery across different platforms
• Created robust CLI interface with dry-run capabilities, flexible output targeting, and comprehensive error handling
• Engineered environment variable inheritance system ensuring generated skills preserve all necessary MCP server requirements