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:

Fetching package source code from npm or PyPI
Analyzing the source with Claude to extract tool definitions
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:

~/.env - Global environment file in your home directory
.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

MCP Servers