ClaudeSkills MCP Server
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@ClaudeSkills MCP Server list all available skills"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
Skills MCP — FastMCP stdio server for Claude Agent Skills
This repository provides a FastMCP stdio server that exposes the Anthropic Claude Agent Skills (folders under skills/) as MCP tools. It lets MCP-aware clients (e.g., Claude Desktop, other MCP agent runtimes) discover, search, and read skills and their assets programmatically.
The server entrypoint is the packaged module skills_mcp.server (console script skills-mcp). It scans the skills/ directory for SKILL.md files conforming to the Agent Skills Spec (YAML frontmatter + Markdown body) and exposes a set of read-only tools.
Repository layout
skills/— Collection of Claude skills. Each skill must contain aSKILL.mdwith YAML frontmatter per the Agent Skills Spec. Note: this folder is gitignored by default; the server can optionally git-sync it at startup.skills_mcp/— Packaged server module (entry:skills_mcp.server) exposing skill discovery/search/read as MCP tools over stdio.pyproject.toml— Project metadata and dependencies (managed viauv).
Related MCP server: skillsmcp
Requirements
Python
>=3.11uvpackage manager installed (https://docs.astral.sh/uv/)A shell to run commands; examples below assume
fish(usesource .venv/bin/activatefor bash/zsh).
Setup with uv
You can either fully sync dependencies from pyproject.toml or install in editable mode:
Create a virtual environment and install:
uv venvsource .venv/bin/activate.fishuv pip install -e .
Or perform a one-shot sync:
uv syncThen activate:
source .venv/bin/activate.fish
Package name: skills-mcp The server depends on:
fastmcppyyaml
Both are declared in pyproject.toml.
Running the server (stdio)
The server uses stdio transport by default when executed as a script. From the repository root:
python -m skills_mcp.serverOr via console script after editable install:
skills-mcp(starts stdio server)CLI/inspection mode:
skills-mcp-cli --list|--detail <NAME>|--search "<QUERY>"|--assets <NAME>|--read <NAME> <PATH>|--serveOr with module:
python -m skills_mcp.server(use flags above)
When launched by an MCP client (e.g., Claude Desktop), the client will spawn this script and connect via stdio automatically.
Server-level documentation
Name: ClaudeSkills MCP Server
Purpose: Exposes Anthropic Claude Agent Skills located in the
skills/folder as MCP tools so agents can discover, search, and read skill guidance and assets.Transport: stdio by default.
Background git sync: On startup, a background thread can clone or pull updates into
skills/. Configure via environment:SKILLS_GIT_URL: git URL for the skills repository (optional)SKILLS_GIT_BRANCH: branch name (default:main)SKILLS_DIR: override skills directory (default:<repo_root>/skills)
Logging: Logs to console and to a rotating file at
logs/skills_mcp_server.logby default. Override withLOG_FILEenvironment variable.
Exposed MCP tools
The server registers the following tools:
list_skills() -> list[dict]Lists all discovered skills with brief metadata.
Returns entries containing
name,description,license?,allowed_tools?,metadata?, andpath(relative toskills/).
get_skill_detail(name: str) -> dict[str, any]Returns the full parsed content of a single skill by
name, including thebody(markdown) and the frontmatter properties.
search_skill_index(query: str) -> list[dict]Case-insensitive substring search across
name,description, and the markdownbody.Returns brief matches with
name,description,path.
list_skill_assets(name: str) -> list[dict]Lists non-
SKILL.mdfiles inside the skill’s directory (recursively).Returns
path(relative to skill),size, andmime_type.
read_skill_asset(name: str, path: str, max_bytes: int = 1048576) -> dict[str, any]Reads a single file inside the given skill.
Returns:
encoding:textorbase64data: UTF-8 text or base64-encoded bytesmime_type: best-effort MIME type guesstruncated:trueifmax_bytescut the file
Notes:
Path traversal is blocked;
pathmust remain within the skill directory.Text vs. binary detection is based on MIME type and UTF-8 decode capability.
Large files are truncated to
max_bytes(defaults to 1 MiB).
Claude Desktop / MCP client integration
Configure your MCP client to launch the console script
skills-mcp(or runpython -m skills_mcp.server) via stdio.If your client supports a configuration object for MCP servers, specify:
transport:stdiocommand:pythonargs:["-m", "skills_mcp.server"]Optionally
cwd: repository rootOptionally
env: relevant environment variables (none required by default)
Different clients format this configuration differently; consult your client’s documentation for the exact shape.
Validating skills
Each skill must satisfy the Agent Skills Spec:
Include a
SKILL.mdstarting with YAML frontmatter delimited by---on its own line at the start and---on its own line when it ends.Required keys:
name: hyphen-case; must match the folder name containing theSKILL.mddescription: concise guidance for when and how the skill should be used
Optional keys:
licenseallowed-toolsmetadata
If parsing fails, the server still returns a placeholder entry for the skill and includes an error message under metadata.
Development notes
Transport: stdio is the default; no extra configuration required.
Logging: console and rotating file logs at
logs/skills_mcp_server.log(configurable viaLOG_FILE); errors parsing invalid skills are reported but do not stop discovery.Security: asset reads are constrained to the skill directory; path traversal is rejected.
MIME types:
guess_typeis used as a best effort; some uncommon types may returnNone.
Tests
After creating the venv and syncing deps, run:
pytest -q.Tests live in
tests/and cover discovery, detail retrieval, asset listing/reading.
Troubleshooting
If your environment complains about missing dependencies, ensure you activated the virtual environment created by
uv venv.If editable install fails due to missing
README.md, ensure this file exists (it should now).If your MCP client cannot find or start the server, check that the
command/argspaths and working directory are correct and that Python>=3.11is used.
Open questions and potential improvements
To tailor this server to your workflow, it would help to clarify:
Should we also expose the skills as MCP resources (e.g., each
SKILL.mdand related assets available viaresource://URIs)?Do you want an HTTP/SSE transport option alongside stdio for remote usage?
Should we add indexing/caching for faster
search_skill_indexon large collections?Any access-control requirements (e.g., filtering certain skills, enforcing
allowed-tools)?Should we enforce stricter validation for nested skill structures (e.g.,
document-skills/docx) or allow folder naming exceptions?Would you like optional rendering helpers (e.g., HTML previews, markdown normalization, or metadata summaries)?
If you want any of the above, or have specific preferences, let me know and I can extend the server accordingly.
Available Tools
13 toolsskill_add_assetA
function_purpose: Add (or optionally overwrite) a single asset file inside an existing skill directory.
Description:
Writes a new file under the skill folder (creating parent directories) while enforcing path safety.
Supports text (UTF-8) or base64 content for binary assets (e.g. PDFs, images).
Will not overwrite existing files unless overwrite=True.
IMPORTANT: After adding an asset, you should ALWAYS create a note (via skill_store_note) documenting:
What the asset contains and its purpose
When and why an agent should load/use it
Any context needed to understand it
Example usage patterns if applicable
This ensures the asset remains discoverable and properly documented for future use.
Args:
name: str Skill name (directory must already exist)
path: str Relative path inside the skill (e.g. "examples/foo.py")
content: str Text content or base64 string
encoding: str "text" (default) or "base64"
overwrite: bool Allow overwriting when True (default False)
Returns:
dict with:
written: bool
path: str Relative normalized path
size: int | None
message: str
binary: bool
Inputs: name (required), path (required), content (required), encoding, +1 more. Returns: object
skill_add_assetsA
function_purpose: Bulk add multiple assets to a skill.
Description:
Convenience wrapper over add_skill_asset for efficiency when scaffolding several files.
Applies a shared overwrite policy (individual entries may still be rejected if invalid).
IMPORTANT: After adding assets, you should ALWAYS create a note (via skill_store_note) documenting:
What each asset contains and its purpose
When and why an agent should load/use them
Any context needed to understand them
Example usage patterns if applicable
Args:
name: str Skill name
assets: list[dict] Each: {path: str, content: str, encoding?: "text"|"base64"}
overwrite: bool Allow overwriting existing files
Returns:
list of result dicts (see add_skill_asset).
Inputs: name (required), assets (required), overwrite. Returns: result
skill_createA
function_purpose: Create a new skill directory containing a SKILL.md per Agent Skills Spec.
Description:
Creates a new directory under the skills root whose name matches the skill 'name' frontmatter.
Writes a SKILL.md file with YAML frontmatter (name, description, optional license, allowed_tools, metadata) followed by the markdown body.
Fails if a skill with that name already exists or if the name is invalid.
Constraints:
Additive only; will not overwrite existing skills.
Name must be hyphen-case or simple alphanumeric with dashes/underscores.
Body may be empty; if empty a placeholder is inserted.
Args:
name: str Skill directory and frontmatter name (hyphen-case recommended)
description: str Concise description of the skill
body: str Markdown guidance content (optional)
license: str | None Optional license identifier/text
allowed_tools: list[str] Optional list of tool names this skill permits
metadata: dict[str, Any] Optional arbitrary metadata mapping
Returns:
dict[str, Any] with:
created: bool
path: str (relative path to SKILL.md within skills dir)
message: str status narrative
Inputs: name (required), description (required), body, license, +2 more. Returns: object
skill_get_detailA
function_purpose: Get full parsed details for a specific skill by name (frontmatter + body + notes).
Description:
Returns the complete parsed skill including frontmatter fields and the markdown body content.
By default, appends all notes from the _notes/ directory to provide complete context including learnings, improvements, corrections, and examples discovered while using the skill.
Args:
name: str The hyphen-case name of the skill (must match the skill directory name)
include_notes: bool If True (default), append notes from _notes/ to the body for complete context
markdown_output: bool If True, return formatted markdown string instead of JSON dict (default: False)
Returns:
If markdown_output=False: dict containing name, description, license?, allowed_tools?, metadata?, path, body
If markdown_output=True: formatted markdown string with frontmatter and body
Usage:
Use this when the agent needs the full guidance text and metadata for a skill.
Notes are included by default to ensure the agent sees all relevant context, corrections, and examples.
Set include_notes=False only if you want just the core SKILL.md content without historical notes.
Set markdown_output=True to get a readable markdown document instead of JSON structure.
Inputs: name (required), include_notes, markdown_output. Returns: result
skill_list_allA
function_purpose: List available skills with brief metadata (excluding body).
Description:
Enumerates all discovered skills from the skills directory and returns summary metadata.
Excludes the markdown body for compact listing; use get_skill_detail for full content.
Args:
markdown_output: bool If True, return formatted markdown string instead of JSON list (default: False)
Returns:
If markdown_output=False: List of dict entries with name, description, license, allowed_tools, metadata, path
If markdown_output=True: formatted markdown string with skill catalog
Usage:
Use this to present a catalog of available skills to the agent or user.
Set markdown_output=True for a more readable format.
Inputs: markdown_output. Returns: result
skill_list_assetsA
function_purpose: List non-SKILL.md files within a skill folder (recursive).
Description:
Enumerates files inside a specific skill directory, excluding SKILL.md, recursively.
Useful for discovering supporting artifacts, reference materials, templates, and helper scripts that belong to a skill.
Args:
name: str The hyphen-case name of the skill whose assets to list
markdown_output: bool If True, return formatted markdown string instead of JSON list (default: False)
Returns:
If markdown_output=False: list of dicts with path, size, mime_type
If markdown_output=True: formatted markdown string with asset listing
Usage:
Call before reading assets to present available files to the agent or user.
For reading actual content, use skill_read_asset() with the returned path.
Set markdown_output=True for a more readable format.
Inputs: name (required), markdown_output. Returns: result
skill_list_notesA
function_purpose: List notes created under a skill's _notes directory.
Description:
Enumerates note files stored under a skill's '_notes' and 'notes' directories. Notes are additive records of learnings, improvements, and scripts created via store_skill_note() or manually, intended to refine or clarify skills over time without editing existing files.
Args:
name: str The hyphen-case skill name (must match the skill directory)
markdown_output: bool If True, return formatted markdown string instead of JSON list (default: False)
Returns:
If markdown_output=False: list of dicts with path, size, title, created_at, kind
If markdown_output=True: formatted markdown string with note listing
Usage:
Use this to browse available notes and select one to read with skill_read_asset().
Set markdown_output=True for a more readable format.
Inputs: name (required), markdown_output. Returns: result
skill_read_assetA
function_purpose: Read a specific asset file within a skill (returns text or base64 data).
Description:
Safely reads an asset inside a skill directory, preventing path traversal and limiting size via max_bytes.
Returns UTF-8 text when possible, otherwise base64-encoded bytes, including a MIME type guess and truncation flag.
Args:
name: str The hyphen-case skill name (must match skill directory)
path: str Relative file path within the skill directory
max_bytes: int Maximum number of bytes to read (default: 8_388_608)
Returns:
dict[str, Any] with:
encoding: "text" | "base64"
data: str UTF-8 text or base64 string
mime_type: str | None Best-effort MIME type guess
truncated: bool True if content was cut at max_bytes
Usage:
Use after listing assets to fetch the content of a specific file for analysis or display.
If the asset is large, consider increasing max_bytes or reading only required portions.
Inputs: name (required), path (required), max_bytes. Returns: object
skill_search_indexA
function_purpose: Search skills by case-insensitive substring across name, description, and body.
Description:
Performs a simple substring search across the parsed name, description, and body for each skill.
Args:
query: str Case-insensitive substring
markdown_output: bool If True, return formatted markdown string instead of JSON list (default: False)
Returns:
If markdown_output=False: List of dicts with name, description, path
If markdown_output=True: formatted markdown string with search results
Usage:
Use this to quickly locate relevant skills by topic or keywords.
Set markdown_output=True for a more readable format.
Inputs: query (required), markdown_output. Returns: result
skill_server_infoA
function_purpose: Return server-level documentation including purpose and usage.
Description:
Provides an overview of the ClaudeSkills MCP Server, its transport mode, and where skills are loaded from.
Useful for clients to show contextual info and help users understand capabilities and configuration.
Returns:
name: str Server name
description: str High-level description of server purpose and capabilities
skills_dir: str Absolute path to the skills directory in use
transport: str Transport used by the server (e.g., "stdio")
Usage:
Call this tool once when connecting, then cache/show details in the client UI or logs.
Inputs: no named parameters. Returns: object
skill_store_noteA
function_purpose: Append a new note to a skill capturing learnings, improvements, and scripts.
Description:
Safely stores additive notes related to a skill (no edits to existing files). Use this to record observations, corrections, suggested improvements, and example scripts discovered while using the skill.
Encourages iterative refinement: if documentation turns out inaccurate or incomplete, add a note that clarifies, extends, or proposes better approaches. Over time, these notes can guide maintainers to improve the canonical SKILL.md.
Constraints:
Additions only. This tool never edits existing files; it only creates new note files.
Notes are stored under a dedicated '_notes' directory within the skill folder.
Args:
name: str The hyphen-case skill name (must match skill directory)
title: str A short, descriptive title for the note
content: str The body of the note (Markdown supported)
Returns:
dict[str, Any] with:
path: str Relative path to the created note within the skill directory
created: bool True on success
message: str Status message
Inputs: name (required), title (required), content (required). Returns: object
skill_trash_user_assetA
function_purpose: Move a user-created asset or note into trash instead of deleting it.
Policy:
For bundled/Anthropic skills:
Only assets under reserved user areas are allowed:
"_user_assets/" subtree
"_user_notes/" subtree
"_notes/" subtree (programmatic notes from skill_store_note)
"notes/" subtree (manually created notes)
Core assets (including SKILL.md and any other non-user files) cannot be trashed.
For user-created skills:
Any asset path under the skill directory may be trashed.
The target file is moved under trash/assets/<skill_name>/__<relative_path>.
Operations are logged in an operations log.
Args:
name: str Skill name
path: str Relative path within the skill directory
Returns:
dict[str, Any] with:
trashed: bool
name: str
path: str
trash_path: str | None
message: str
Inputs: name (required), path (required). Returns: object
skill_trash_user_skillA
function_purpose: Move a user-created skill directory into a trash location instead of hard deleting it.
Policy:
Only user-created skills may be trashed. Bundled/Anthropic skills are rejected.
The skill directory is moved under a trash/skills subdirectory with a timestamped folder name.
All operations are logged to an operations log file.
Args:
name: str Skill name to trash
force: bool Require explicit confirmation flag (default True). If False, the call is a dry refusal.
Returns:
dict[str, Any] with:
trashed: bool
name: str
trash_path: str | None
message: str
Inputs: name (required), force. Returns: object
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 13 tools
Every tool targets a distinct resource or action: server info, skill listing/detail/search, asset listing/reading, creation, asset addition (single/bulk), note storage/listing, and trashing of skills/assets. The only near-overlap between add_asset and add_assets is clearly differentiated by singular vs. bulk, and descriptions make the boundaries explicit.
All tools share the 'skill_' prefix and mostly follow a verb_noun pattern (list_all, get_detail, search_index, read_asset, add_asset, store_note, trash_user_skill). Two deviations exist: 'skill_server_info' lacks a verb, and 'skill_create' lacks a noun, but these are minor and do not obscure the overall pattern.
With 13 tools, the server is well-scoped for a skills management domain. Each tool covers a distinct function—from discovery and reading to creation and maintenance—without redundancy or bloat, fitting comfortably within the ideal 3-15 range.
The surface covers the core lifecycle well: create, read, list, search, asset management, notes, and trash. However, there is no direct way to update or edit the core SKILL.md body or frontmatter after creation; users must rely on notes or recreate, which is a notable gap for a management tool.
Maintenance
Related MCP Connectors
Governed AI agent skills — one library, distributed to devs and exposed to remote agents over MCP.
AI Visibility and Content Intelligence tools for Claude and MCP-compatible agents.
Search and discover Agent Skills from the skills.sh registry. Powered by HAPI MCP server.
Hosted MCP server for live public-data APIs and Skills for AI agents.
Related MCP Servers
- AlicenseNot gradedqualityDmaintenanceTurns Claude-style skills (SKILL.md files with resources) into callable MCP tools for any agent. Discovers skills from a directory, exposes their instructions and resources, and can execute bundled helper scripts.144 PyPI409MIT
- AlicenseAqualityDmaintenanceExposes Agent Skills to AI agents as MCP tools, enabling discovery and activation of skill instructions for coding agents.327MIT
- AlicenseAqualityCmaintenanceMCP server that exposes a pool of Claude SDK agents as tools, enabling deterministic agent creation, retrieval, and resumption from a capability corpus.10112 PyPI1MIT
- AlicenseNot gradedqualityBmaintenanceEnables MCP clients to discover, search, and load agent skills from many sources, including other agents' skill directories, Claude Code plugin marketplaces, and remote git repositories, with no copying or syncing required.806 npm7MIT