MCP Skills Server MCP server

MCP Skills Server

A production-ready Model Context Protocol (MCP) server that dynamically loads and exposes skills from a mounted volume with hot-reloading support.

📦 Available on MCP Registry - Install with one command!

Features

• Dynamic Skill Loading: Automatically discovers and loads skills from a directory
• Hot-Reloading: Detects changes to SKILL.md files and reloads without restart
• Folder Structure Validation: Enforces best practices with clear error messages
• MCP Protocol Compliant: Full implementation of resources and tools
• Production Ready: Comprehensive error handling, logging, and validation
• Docker Support: Run in containers with volume mounting
• Type Safe: Full type hints using Python 3.13 features
• Well Tested: >80% code coverage with comprehensive test suite

Table of Contents

• Skills Directory Structure
• Quick Start
• Installation
• Usage
• Configuration
• Skill File Format
• MCP Resources and Tools
• Development
• Troubleshooting
• Contributing
• License

Skills Directory Structure

CRITICAL REQUIREMENT: Each skill MUST be in its own dedicated folder within the skills directory. The server will ONLY recognize skills that follow this structure.

✅ Valid Structure

your-skills-directory/
├── skill-one/
│   └── SKILL.md          ← Required
├── skill-two/
│   ├── SKILL.md          ← Required
│   └── examples/         ← Optional
│       └── example.py
└── skill-three/
    ├── SKILL.md
    ├── examples/
    │   └── demo.py
    └── templates/
        └── template.txt

❌ Invalid Structures (Will Be Ignored)

your-skills-directory/
├── SKILL.md                  ❌ Not in a folder - WILL BE SKIPPED
├── random-file.txt           ❌ Not a skill folder
├── .hidden-folder/           ❌ Hidden folder - WILL BE SKIPPED
│   └── SKILL.md
└── __pycache__/              ❌ System folder - WILL BE SKIPPED
    └── SKILL.md

Folder Naming Conventions

Valid folder names:

• Lowercase with hyphens: my-skill-name
• Lowercase with underscores: excel_advanced
• Alphanumeric: skill-name-v2

Invalid (will be skipped):

• Hidden folders starting with .
• Private folders starting with _
• System folders: pycache, node_modules, .git, etc.

Quick Start

Using Docker (Recommended)

1. Create your skills directory:

mkdir -p ~/claude-skills/my-first-skill

1. Create a skill file:

cat > ~/claude-skills/my-first-skill/SKILL.md << 'EOF'
---
name: "my-first-skill"
description: "My first Claude skill"
---

# My First Skill

This is my first skill for Claude!

## Usage

Simply describe what your skill does here.
EOF

1. Run the server:

docker run -i --rm \
  -v ~/claude-skills:/skills:ro \
  mcp-skill-hub

Using Poetry (Development)

1. Clone and install:

Shortened. The full README is on GitHub.