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

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.