MCP Skills Server

MCP server that loads and serves skills from a mounted directory with hot reload.

Quick Install

Automated & IDE Setup

Copy the AI prompt to install this server into Claude Code, Cursor, or another agent — or use 1-click editor setup below.

Add to Cursor Add to VS Code

Manual Client & Custom JSON ConfigExpand JSON ▾

Client Config & Setup

Choose your client or environment

Target File:~/Library/Application Support/Claude/claude_desktop_config.json

claude_desktop_config.json

{
  "mcpServers": {
    "mcp-skills-server": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-skills-server"
      ]
    }
  }
}

💡 Paste the JSON block into your client's configuration file under mcpServers, then restart the application.

Documentation Overview

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

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

Code

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)

Code

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)

Create your skills directory:

bash

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

Create a skill file:

bash

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

Run the server:

Terminal

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

Using Poetry (Development)

Clone and install:

bash

git clone https://github.com/srprasanna/mcp-skill-hub.git
cd mcp-skill-hub
poetry install

Create your skills directory:

bash

mkdir -p ~/claude-skills/my-first-skill
# Create SKILL.md as shown above

Run the server:

server.ts

export MCP_SKILLS_DIR=~/claude-skills
poetry run mcp-skills

Installation

Prerequisites

Python 3.13+ (for development)
Poetry 1.7+ (for dependency management)
Docker (optional, for containerized deployment)

Install with Poetry

bash

# Clone the repository
git clone https://github.com/srprasanna/mcp-skill-hub.git
cd mcp-skill-hub

# Install dependencies
poetry install

# Verify installation
poetry run mcp-skills --help

Build Docker Image

bash

# Build the image
docker build -t mcp-skill-hub .

# Or use docker-compose
docker-compose build

Usage

Running Locally

server.ts

# Set the skills directory
export MCP_SKILLS_DIR=/path/to/your/skills

# Run the server
poetry run mcp-skills

Running with Docker

Terminal

docker run -i --rm \
  -v /path/to/your/skills:/skills:ro \
  -e MCP_SKILLS_LOG_LEVEL=INFO \
  mcp-skill-hub

Running with Docker Compose

bash

# Edit docker-compose.yml to set your skills directory path
docker-compose up mcp-skills

Integrating with Claude Desktop

Add to your Claude Desktop configuration (claude_desktop_config.json):

config.json

{
  "mcpServers": {
    "skills": {
      "command": "docker",
      "args": [
        "run",
        "-i",
        "--rm",
        "-v",
        "${HOME}/claude-skills:/skills:ro",
        "mcp-skill-hub"
      ]
    }
  }
}

Or using Poetry:

config.json

{
  "mcpServers": {
    "skills": {
      "command": "poetry",
      "args": ["run", "mcp-skills"],
      "cwd": "/path/to/mcp-skill-hub",
      "env": {
        "MCP_SKILLS_DIR": "/path/to/your/skills"
      }
    }
  }
}

Important: Make sure your ${HOME}/claude-skills directory contains skill folders, not loose SKILL.md files!

Configuration

Configuration is done via environment variables with the prefix MCP_SKILLS_:

Variable	Default	Description
`MCP_SKILLS_DIR`	`/skills`	Root directory containing skill folders
`MCP_SKILLS_HOT_RELOAD`	`true`	Enable automatic reloading
`MCP_SKILLS_DEBOUNCE_DELAY`	`0.5`	Delay (seconds) before reload
`MCP_SKILLS_LOG_LEVEL`	`INFO`	Log level (DEBUG, INFO, WARNING, ERROR)
`MCP_SKILLS_SCAN_DEPTH`	`1`	Scan depth (always 1)

Example .env File

bash

MCP_SKILLS_DIR=/path/to/skills
MCP_SKILLS_HOT_RELOAD=true
MCP_SKILLS_DEBOUNCE_DELAY=0.5
MCP_SKILLS_LOG_LEVEL=INFO

Skill File Format

Skills are defined in SKILL.md files with YAML frontmatter:

Minimal Example

markdown

---
name: "my-skill"
description: "Brief description"
---

# My Skill

Your skill content here in Markdown.

Complete Example

markdown

---
# Required fields
name: "excel-advanced"
description: "Advanced Excel automation techniques"

# Version and authorship
version: "1.2.0"
author: "Your Name"
created: "2025-01-15"
updated: "2025-10-23"

# Dependencies
dependencies:
  python: ["openpyxl>=3.0.0", "pandas>=2.0.0"]
  system: ["libreoffice"]

# Categorization
category: "office-automation"
tags: ["excel", "spreadsheet", "automation"]
complexity: "intermediate"  # beginner|intermediate|advanced

# Usage guidance
when_to_use:
  - "Automating Excel report generation"
  - "Processing multiple Excel files"
  - "Creating complex formulas programmatically"

# Relationships
related_skills: ["csv-processing", "data-analysis"]

# Examples
has_examples: true
example_files: ["examples/report_generator.py", "templates/report_template.xlsx"]
---

# Excel Advanced Automation

This skill covers advanced Excel automation techniques...

## Features

- Automated report generation
- Formula creation
- Bulk processing

## Examples

See `examples/report_generator.py` for a working example.

Available Metadata Fields

Required:

name: Unique identifier (kebab-case recommended)
description: Brief description

Optional:

version: Semantic version
author: Creator name
created, updated: ISO dates (YYYY-MM-DD)
dependencies: Python packages or system tools
category: Main category for grouping
tags: Array of tags for search
complexity: beginner, intermediate, or advanced
when_to_use: Array of usage scenarios
related_skills: Names of related skills
has_examples: Boolean flag
example_files: Paths to example files (relative to skill folder)

MCP Resources and Tools

Resources

The server exposes these MCP resources:

skill://catalog - JSON catalog of all skills with metadata
skill://{name} - Individual skill markdown content

Tools

Four tools are available for interacting with skills:

1. `search_skills`

Search for skills by query, category, tag, or complexity.

config.json

{
  "query": "excel",
  "category": "office-automation",
  "tag": "automation",
  "complexity": "intermediate"
}

2. `reload_skills`

Manually trigger a reload of all skills from the directory.

config.json

{}

3. `get_skill_info`

Get metadata for a specific skill without loading full content.

config.json

{
  "name": "excel-advanced"
}

4. `list_skill_folders`

List all valid skill folders found in the skills directory.

config.json

{}

Development

Setup Development Environment

bash

# Clone repository
git clone https://github.com/srprasanna/mcp-skill-hub.git
cd mcp-skill-hub

# Install dependencies (including dev dependencies)
poetry install

# Activate virtual environment
poetry shell

Running Tests

bash

# Run all tests
poetry run pytest

# Run with coverage
poetry run pytest --cov=mcp_skills --cov-report=html

# Run specific test file
poetry run pytest tests/test_scanner.py

# Run with verbose output
poetry run pytest -v

Code Quality

bash

# Format code
poetry run black .

Read the full README →View source on GitHub →

Related MCP Servers

View all in Developer Tools View all alternatives

Reviews

No reviews yet — be the first to share how this listing worked for you.

Frequently Asked Questions about MCP Skills Server

Add the following block to your claude_desktop_config.json under mcpServers: "mcpServers": { "mcp-skills-server": { "command": "npx", "args": ["-y", "MCP Skills Server"] } }

AllMCPs Directory Badge

Full Badge Customizer

Showcase your server listing on GitHub or your project documentation. Embed this dynamic SVG badge to highlight official listing status and live engagement.

Badge Style:

Live Dynamic SVG Preview

MCP Skills Server AllMCPs Directory Badge

Markdown (GitHub README)

[![AllMCPs](https://allmcps.com/api/badge/mcp-skills-server?style=directory)](https://allmcps.com/mcp/mcp-skills-server)

HTML Embed

<a href="https://allmcps.com/mcp/mcp-skills-server"><img src="https://allmcps.com/api/badge/mcp-skills-server?style=directory" alt="MCP Skills Server on AllMCPs" /></a>

Technical Specs & Signals

CategoryDeveloper Tools

27Quality signal: Emerging · 27/100How this signal is calculated ▾

Server availabilityNot measured

Not scored for repo-hosted servers — we can't reach the running server, only its GitHub page. Hosted MCP endpoints are health-checked live.

Verified ownership8/20

Documentation & tools11/30

Adoption & activity1/15

Community engagement0/10

A guidance signal from public completeness & health data — not a user rating. New listings start lower and rise as they add docs, get verified, and grow adoption. Signals we can't observe for a listing are skipped, not counted against it.

★ Featured

Moxie Docs MCP

MCP & Agent Skills for Automated Documentation, and codebase conventions + context

Explore Server →

Own this project?

This directory is pre-filled from public sources. Claim via GitHub README, site badge, or DNS TXT to unlock edit access and the Official badge — proof is checked automatically, then reviewed by our team.

Free dofollow backlink: add your website and place the AllMCPs badge on it — no claim needed. We detect it automatically and keep it verified as long as the badge stays live.

Claim & get free dofollow

Share & Embed

Add our SVG badge (dark/light directory styles) or embeddable widget to your site.

Explore more

More in 💻 Developer Tools →Best MCP servers for Developers →Alternatives to MCP Skills Server →Install in Claude Desktop Install in Cursor Install in VS Code

MCP Skills Server

MCP server that loads and serves skills from a mounted directory with hot reload.

Quick Install

Automated & IDE Setup

Copy the AI prompt to install this server into Claude Code, Cursor, or another agent — or use 1-click editor setup below.

Add to Cursor Add to VS Code

Manual Client & Custom JSON ConfigExpand JSON ▾

Client Config & Setup

Choose your client or environment

Target File:~/Library/Application Support/Claude/claude_desktop_config.json

claude_desktop_config.json

{
  "mcpServers": {
    "mcp-skills-server": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-skills-server"
      ]
    }
  }
}

💡 Paste the JSON block into your client's configuration file under mcpServers, then restart the application.

Documentation Overview

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

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

Code

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)

Code

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)

Create your skills directory:

bash

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

Create a skill file:

bash

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

Run the server:

Terminal

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

Using Poetry (Development)

Clone and install:

bash

git clone https://github.com/srprasanna/mcp-skill-hub.git
cd mcp-skill-hub
poetry install

Create your skills directory:

bash

mkdir -p ~/claude-skills/my-first-skill
# Create SKILL.md as shown above

Run the server:

server.ts

export MCP_SKILLS_DIR=~/claude-skills
poetry run mcp-skills

Installation

Prerequisites

Python 3.13+ (for development)
Poetry 1.7+ (for dependency management)
Docker (optional, for containerized deployment)

Install with Poetry

bash

# Clone the repository
git clone https://github.com/srprasanna/mcp-skill-hub.git
cd mcp-skill-hub

# Install dependencies
poetry install

# Verify installation
poetry run mcp-skills --help

Build Docker Image

bash

# Build the image
docker build -t mcp-skill-hub .

# Or use docker-compose
docker-compose build

Usage

Running Locally

server.ts

# Set the skills directory
export MCP_SKILLS_DIR=/path/to/your/skills

# Run the server
poetry run mcp-skills

Running with Docker

Terminal

docker run -i --rm \
  -v /path/to/your/skills:/skills:ro \
  -e MCP_SKILLS_LOG_LEVEL=INFO \
  mcp-skill-hub

Running with Docker Compose

bash

# Edit docker-compose.yml to set your skills directory path
docker-compose up mcp-skills

Integrating with Claude Desktop

Add to your Claude Desktop configuration (claude_desktop_config.json):

config.json

{
  "mcpServers": {
    "skills": {
      "command": "docker",
      "args": [
        "run",
        "-i",
        "--rm",
        "-v",
        "${HOME}/claude-skills:/skills:ro",
        "mcp-skill-hub"
      ]
    }
  }
}

Or using Poetry:

config.json

{
  "mcpServers": {
    "skills": {
      "command": "poetry",
      "args": ["run", "mcp-skills"],
      "cwd": "/path/to/mcp-skill-hub",
      "env": {
        "MCP_SKILLS_DIR": "/path/to/your/skills"
      }
    }
  }
}

Important: Make sure your ${HOME}/claude-skills directory contains skill folders, not loose SKILL.md files!

Configuration

Configuration is done via environment variables with the prefix MCP_SKILLS_:

Variable	Default	Description
`MCP_SKILLS_DIR`	`/skills`	Root directory containing skill folders
`MCP_SKILLS_HOT_RELOAD`	`true`	Enable automatic reloading
`MCP_SKILLS_DEBOUNCE_DELAY`	`0.5`	Delay (seconds) before reload
`MCP_SKILLS_LOG_LEVEL`	`INFO`	Log level (DEBUG, INFO, WARNING, ERROR)
`MCP_SKILLS_SCAN_DEPTH`	`1`	Scan depth (always 1)

Example .env File

bash

MCP_SKILLS_DIR=/path/to/skills
MCP_SKILLS_HOT_RELOAD=true
MCP_SKILLS_DEBOUNCE_DELAY=0.5
MCP_SKILLS_LOG_LEVEL=INFO

Skill File Format

Skills are defined in SKILL.md files with YAML frontmatter:

Minimal Example

markdown

---
name: "my-skill"
description: "Brief description"
---

# My Skill

Your skill content here in Markdown.

Complete Example

markdown

---
# Required fields
name: "excel-advanced"
description: "Advanced Excel automation techniques"

# Version and authorship
version: "1.2.0"
author: "Your Name"
created: "2025-01-15"
updated: "2025-10-23"

# Dependencies
dependencies:
  python: ["openpyxl>=3.0.0", "pandas>=2.0.0"]
  system: ["libreoffice"]

# Categorization
category: "office-automation"
tags: ["excel", "spreadsheet", "automation"]
complexity: "intermediate"  # beginner|intermediate|advanced

# Usage guidance
when_to_use:
  - "Automating Excel report generation"
  - "Processing multiple Excel files"
  - "Creating complex formulas programmatically"

# Relationships
related_skills: ["csv-processing", "data-analysis"]

# Examples
has_examples: true
example_files: ["examples/report_generator.py", "templates/report_template.xlsx"]
---

# Excel Advanced Automation

This skill covers advanced Excel automation techniques...

## Features

- Automated report generation
- Formula creation
- Bulk processing

## Examples

See `examples/report_generator.py` for a working example.

Available Metadata Fields

Required:

name: Unique identifier (kebab-case recommended)
description: Brief description

Optional:

version: Semantic version
author: Creator name
created, updated: ISO dates (YYYY-MM-DD)
dependencies: Python packages or system tools
category: Main category for grouping
tags: Array of tags for search
complexity: beginner, intermediate, or advanced
when_to_use: Array of usage scenarios
related_skills: Names of related skills
has_examples: Boolean flag
example_files: Paths to example files (relative to skill folder)

MCP Resources and Tools

Resources

The server exposes these MCP resources:

skill://catalog - JSON catalog of all skills with metadata
skill://{name} - Individual skill markdown content

Tools

Four tools are available for interacting with skills:

1. `search_skills`

Search for skills by query, category, tag, or complexity.

config.json

{
  "query": "excel",
  "category": "office-automation",
  "tag": "automation",
  "complexity": "intermediate"
}

2. `reload_skills`

Manually trigger a reload of all skills from the directory.

config.json

{}

3. `get_skill_info`

Get metadata for a specific skill without loading full content.

config.json

{
  "name": "excel-advanced"
}

4. `list_skill_folders`

List all valid skill folders found in the skills directory.

config.json

{}

Development

Setup Development Environment

bash

# Clone repository
git clone https://github.com/srprasanna/mcp-skill-hub.git
cd mcp-skill-hub

# Install dependencies (including dev dependencies)
poetry install

# Activate virtual environment
poetry shell

Running Tests

bash

# Run all tests
poetry run pytest

# Run with coverage
poetry run pytest --cov=mcp_skills --cov-report=html

# Run specific test file
poetry run pytest tests/test_scanner.py

# Run with verbose output
poetry run pytest -v

Code Quality

bash

# Format code
poetry run black .

Read the full README →View source on GitHub →

Related MCP Servers

View all in Developer Tools View all alternatives

Reviews

No reviews yet — be the first to share how this listing worked for you.

Frequently Asked Questions about MCP Skills Server

Add the following block to your claude_desktop_config.json under mcpServers: "mcpServers": { "mcp-skills-server": { "command": "npx", "args": ["-y", "MCP Skills Server"] } }

AllMCPs Directory Badge

Full Badge Customizer

Showcase your server listing on GitHub or your project documentation. Embed this dynamic SVG badge to highlight official listing status and live engagement.

Badge Style:

Live Dynamic SVG Preview

Markdown (GitHub README)

[![AllMCPs](https://allmcps.com/api/badge/mcp-skills-server?style=directory)](https://allmcps.com/mcp/mcp-skills-server)

HTML Embed

<a href="https://allmcps.com/mcp/mcp-skills-server"><img src="https://allmcps.com/api/badge/mcp-skills-server?style=directory" alt="MCP Skills Server on AllMCPs" /></a>

Technical Specs & Signals

CategoryDeveloper Tools

27Quality signal: Emerging · 27/100How this signal is calculated ▾

Server availabilityNot measured

Not scored for repo-hosted servers — we can't reach the running server, only its GitHub page. Hosted MCP endpoints are health-checked live.

Verified ownership8/20

Documentation & tools11/30

Adoption & activity1/15

Community engagement0/10

★ Featured

Moxie Docs MCP

MCP & Agent Skills for Automated Documentation, and codebase conventions + context

Explore Server →

Own this project?

Free dofollow backlink: add your website and place the AllMCPs badge on it — no claim needed. We detect it automatically and keep it verified as long as the badge stays live.

Claim & get free dofollow

Share & Embed

Add our SVG badge (dark/light directory styles) or embeddable widget to your site.

Explore more

More in 💻 Developer Tools →Best MCP servers for Developers →Alternatives to MCP Skills Server →Install in Claude Desktop Install in Cursor Install in VS Code

MCP Skills Server

Quick Install

Client Config & Setup

Documentation Overview

MCP Skills Server

Features

Table of Contents

Skills Directory Structure

✅ Valid Structure

❌ Invalid Structures (Will Be Ignored)

Folder Naming Conventions

Quick Start

Using Docker (Recommended)

Using Poetry (Development)

Installation

Prerequisites

Install with Poetry

Build Docker Image

Usage

Running Locally

Running with Docker

Running with Docker Compose

Integrating with Claude Desktop

Configuration

Example .env File

Skill File Format

Minimal Example

Complete Example

Available Metadata Fields

MCP Resources and Tools

Resources

Tools

1. search_skills

2. reload_skills

3. get_skill_info

4. list_skill_folders

Development

Setup Development Environment

Running Tests

Code Quality

Related MCP Servers

Reviews

Frequently Asked Questions about MCP Skills Server

AllMCPs Directory Badge

Technical Specs & Signals

Moxie Docs MCP

Own this project?

Share & Embed

Explore more

MCP Skills Server

Quick Install

Client Config & Setup

Documentation Overview

MCP Skills Server

Features

Table of Contents

Skills Directory Structure

✅ Valid Structure

❌ Invalid Structures (Will Be Ignored)

Folder Naming Conventions

Quick Start

Using Docker (Recommended)

Using Poetry (Development)

Installation

Prerequisites

Install with Poetry

Build Docker Image

Usage

Running Locally

Running with Docker

Running with Docker Compose

Integrating with Claude Desktop

Configuration

Example .env File

Skill File Format

Minimal Example

Complete Example

Available Metadata Fields

MCP Resources and Tools

Resources

1. `search_skills`

2. `reload_skills`

3. `get_skill_info`

4. `list_skill_folders`

1. `search_skills`

2. `reload_skills`

3. `get_skill_info`

4. `list_skill_folders`