Skip to main content
Glama

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 a SKILL.md with 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 via uv).

Related MCP server: skillsmcp

Requirements

  • Python >=3.11

  • uv package manager installed (https://docs.astral.sh/uv/)

  • A shell to run commands; examples below assume fish (use source .venv/bin/activate for 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 venv

    • source .venv/bin/activate.fish

    • uv pip install -e .

  • Or perform a one-shot sync:

    • uv sync

    • Then activate:

    • source .venv/bin/activate.fish

Package name: skills-mcp The server depends on:

  • fastmcp

  • pyyaml

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.server

  • Or 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> | --serve

  • Or 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.log by default. Override with LOG_FILE environment 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?, and path (relative to skills/).

  • get_skill_detail(name: str) -> dict[str, any]

    • Returns the full parsed content of a single skill by name, including the body (markdown) and the frontmatter properties.

  • search_skill_index(query: str) -> list[dict]

    • Case-insensitive substring search across name, description, and the markdown body.

    • Returns brief matches with name, description, path.

  • list_skill_assets(name: str) -> list[dict]

    • Lists non-SKILL.md files inside the skill’s directory (recursively).

    • Returns path (relative to skill), size, and mime_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: text or base64

      • data: UTF-8 text or base64-encoded bytes

      • mime_type: best-effort MIME type guess

      • truncated: true if max_bytes cut the file

Notes:

  • Path traversal is blocked; path must 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 run python -m skills_mcp.server) via stdio.

  • If your client supports a configuration object for MCP servers, specify:

    • transport: stdio

    • command: python

    • args: ["-m", "skills_mcp.server"]

    • Optionally cwd: repository root

    • Optionally 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.md starting 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 the SKILL.md

    • description: concise guidance for when and how the skill should be used

  • Optional keys:

    • license

    • allowed-tools

    • metadata

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 via LOG_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_type is used as a best effort; some uncommon types may return None.

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/args paths and working directory are correct and that Python >=3.11 is 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.md and related assets available via resource:// URIs)?

  • Do you want an HTTP/SSE transport option alongside stdio for remote usage?

  • Should we add indexing/caching for faster search_skill_index on 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 tools
skill_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

    A4.5/5.0

    Scored across 13 tools

    Disambiguation5/5

    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.

    Naming Consistency4/5

    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.

    Tool Count5/5

    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.

    Completeness4/5

    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

    ActivityNo data
    ResponsivenessOutdated data

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      Not graded
      quality
      D
      maintenance
      Turns 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 PyPI
      409
      MIT
    • A
      license
      A
      quality
      D
      maintenance
      Exposes Agent Skills to AI agents as MCP tools, enabling discovery and activation of skill instructions for coding agents.
      3
      27
      MIT
    • A
      license
      Not graded
      quality
      B
      maintenance
      Enables 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 npm
      7
      MIT