mcp-to-skills

Convert MCP (Model Context Protocol) servers into Claude Code skills.

Overview

mcp-to-skills automatically converts MCP server configurations into Claude Code skills by:

1. Fetching package source code from npm or PyPI
2. Analyzing the source with Claude to extract tool definitions
3. Generating skill files with documentation and wrapper scripts

Installation

pip install mcp-to-skills

Or with uv:

uv pip install mcp-to-skills

Quick Start

1. Set up your API key

export ANTHROPIC_API_KEY="sk-ant-..."

Or add it to a .env file (see Environment Variables below).

2. List your MCP servers

mcp-to-skills list

3. Convert a server to a skill

mcp-to-skills convert --mcp sqlite --claude

4. Use the generated skill

uv run ~/.claude/skills/sqlite/scripts/read_query.py --query "SELECT * FROM users"

Commands

mcp-to-skills list [CONFIG_PATH]

List MCP servers in a configuration file.

# Auto-detect config
mcp-to-skills list

# Explicit path
mcp-to-skills list /path/to/config.json

mcp-to-skills convert [CONFIG_PATH] [OPTIONS]

Convert MCP server(s) to Claude Code skills.

| Option | Description | |--------|-------------| | --mcp, -m | Convert only this server by name | | --output, -o | Output directory (default: ./skills) | | --claude | Output to ~/.claude/skills/ | | --cursor | Output to ~/.cursor/skills/ | | --dry-run, -n | Preview without writing files |

# Convert specific server
mcp-to-skills convert --mcp filesystem

# Convert all servers to Claude Code
mcp-to-skills convert --claude

# Preview output
mcp-to-skills convert --dry-run

Configuration

The CLI auto-detects configuration files from:

• ~/Library/Application Support/Claude/claude_desktop_config.json (macOS)
• ~/.config/claude/claude_desktop_config.json (Linux)
• ./mcp-servers.json (current directory)

Supported Formats

Claude Desktop format:

{
  "mcpServers": {
    "sqlite": {
      "command": "uv",
      "args": ["run", "mcp-server-sqlite", "--db", "/data/app.db"]
    }
  }
}

Flat format:

{
  "sqlite": {
    "command": "uv",
    "args": ["run", "mcp-server-sqlite"]
  }
}

Output

For each MCP server, mcp-to-skills generates:

skills/sqlite/
├── SKILL.md           # Skill manifest with documentation
└── scripts/
    ├── read_query.py  # PEP 723 wrapper scripts
    ├── write_query.py
    └── list_tables.py

SKILL.md

Contains:

• Frontmatter with name and description
• Tool documentation with parameters
• Environment variable requirements
• Usage examples

Wrapper Scripts

Python scripts with:

• PEP 723 inline dependencies (works with uv run)
• argparse CLI interface
• JSON output option (--json)
• Error handling

Requirements

• Python 3.11+
• ANTHROPIC_API_KEY environment variable
• npm (for npm-based MCP servers)
• pip (for Python-based MCP servers)

Environment Variables

mcp-to-skills automatically loads environment variables from .env files:

1. ~/.env - Global environment file in your home directory
2. .env - Local environment file in the current directory

Local .env takes precedence over the global one.

Example .env File

# ~/.env or ./.env
ANTHROPIC_API_KEY=sk-ant-...

MCP servers can also specify environment variables in their config using the env key. See examples/ for more configurations.

Documentation

| Section | Description | |---------|-------------| | Getting Started | Installation and first conversion | | Configuration | Config file formats | | Examples | Sample MCP server configurations | | CLI Reference | Complete command docs | | Architecture | Technical design | | Troubleshooting | Common issues |

Development

# Clone and install
git clone https://github.com/fakoli/mcp-to-skills.git
cd mcp-to-skills
uv sync --dev

# Run tests
uv run pytest

# Type check
uv run pyright src/

# Lint
uv run ruff check src/

See CONTRIBUTING.md for contribution guidelines.

License

MIT