Skill-to-MCP

# Skill-to-MCP [](https://biocontext.ai/registry) [![Tests][badge-tests]][tests] [![Documentation][badge-docs]][documentation] [][pypi] [][pypi] [badge-tests]: https://img.shields.io/github/actions/workflow/status/biocontext-ai/skill-to-mcp/test.yaml?branch=main [badge-docs]: https://img.shields.io/readthedocs/skill-to-mcp Convert AI Skills (following Claude Skills format) into MCP server resources, making them accessible through the Model Context Protocol. > **Part of [BioContextAI](https://biocontext.ai)** - A community-driven initiative connecting agentic AI with biomedical resources through standardized MCP servers. While this package is domain-agnostic and can be used for any skill collection, it was developed to support the biomedical research community. ## Overview This MCP server exposes Claude Skills as resources that can be accessed by LLM applications through the Model Context Protocol. Skills are self-contained directories containing a `SKILL.md` file with YAML frontmatter, along with supporting files like scripts, references, and examples. ### Features - **Automatic skill discovery**: Recursively finds all `SKILL.md` files in the `skills/` directory - **Frontmatter parsing**: Extracts skill metadata (name, description) from YAML frontmatter - **Three core tools**: - `get_available_skills`: Lists all available skills with descriptions - `get_skill_details`: Returns SKILL.md content and file listing for a specific skill - `get_skill_related_file`: Reads any file within a skill directory (with directory traversal protection) - **Security**: Path validation prevents access outside skill directories ## Getting Started Please refer to the [documentation][] for comprehensive guides, or jump to: - [Configuration](#configuration) - Set up your skills directory - [Usage](#usage) - Learn about the three core tools - [Creating Skills](#creating-skills) - Build your own skills - [Installation](#installation) - Multiple installation options ### Quick Links - **Documentation**: [skill-to-mcp.readthedocs.io][documentation] - **BioContextAI Registry**: [biocontext.ai/registry][registry] - **API Reference**: [API documentation][] - **Source Code**: [GitHub][source] - **Issue Tracker**: [GitHub Issues][issue tracker] ## Configuration The MCP server requires a skills directory to be specified. This allows you to: - Install the package separately from your skills - Edit skills without modifying the package - Use different skill collections for different projects Set the skills directory using either: - Command-line option: `--skills-dir /path/to/skills` - Environment variable: `SKILLS_DIR=/path/to/skills` ### Example Configuration for MCP Clients ```json { "mcpServers": { "skill-to-mcp": { "command": "uvx", "args": ["skill_to_mcp", "--skills-dir", "/path/to/your/skills"], "env": { "UV_PYTHON": "3.12" } } } } ``` Or using environment variables: ```json { "mcpServers": { "skill-to-mcp": { "command": "uvx", "args": ["skill_to_mcp"], "env": { "UV_PYTHON": "3.12", "SKILLS_DIR": "/path/to/your/skills" } } } } ``` ## Usage Once configured in your MCP client, the server provides three tools: ### get_available_skills Returns a list of all available skills with metadata: ```json [ { "name": "single-cell-rna-qc", "description": "Performs quality control on single-cell RNA-seq data...", "path": "/path/to/skills/single-cell-rna-qc" } ] ``` ### get_skill_details Returns the full SKILL.md content and list of files for a specific skill: ```json { "skill_content": "---\nname: single-cell-rna-qc\n...", "files": ["SKILL.md", "scripts/qc_analysis.py", "references/guidelines.md"] } ``` The `return_type` parameter controls what data is returned: - `"content"`: Returns only the SKILL.md content as text - `"file_path"`: Returns only the absolute path to SKILL.md - `"both"` (default): Returns both content and file path in a dict ### get_skill_related_file Reads a specific file within a skill directory: ```python get_skill_related_file( skill_name="single-cell-rna-qc", relative_path="scripts/qc_analysis.py", return_type="content" # "content", "file_path", or "both" (default) ) ``` ### Example Configurations #### Claude Desktop Configuration Add to your `claude_desktop_config.json`: ```json { "mcpServers": { "biomedical-skills": { "command": "uvx", "args": [ "skill_to_mcp", "--skills-dir", "/Users/yourname/biomedical-skills" ], "env": { "UV_PYTHON": "3.12" } } } } ``` #### Multiple Skill Collections You can run multiple instances with different skill directories: ```json { "mcpServers": { "biomedical-skills": { "command": "uvx", "args": ["skill_to_mcp", "--skills-dir", "/path/to/biomedical-skills"] }, "data-science-skills": { "command": "uvx", "args": ["skill_to_mcp", "--skills-dir", "/path/to/data-science-skills"] } } } ``` ## Creating Skills Skills should be placed in your configured skills directory. Each skill must: 1. Have its own subdirectory 2. Contain a `SKILL.md` file with YAML frontmatter 3. Follow the frontmatter format: ```markdown --- name: my-skill-name description: Brief description of what this skill does and when to use it --- # Skill Content Instructions and documentation go here... ``` ### Skill Naming Requirements - Use lowercase letters, numbers, and hyphens only - Maximum 64 characters - No XML tags or reserved words See the included example `skills/single-cell-rna-qc/SKILL.md` for a complete reference. ### Example Skills Directory Structure ``` my-skills/ ├── skill-1/ │ ├── SKILL.md │ ├── scripts/ │ └── references/ ├── skill-2/ │ ├── SKILL.md │ └── data/ └── skill-3/ └── SKILL.md ``` ## Installation You need to have Python 3.11 or newer installed on your system. If you don't have Python installed, we recommend installing [uv][]. There are several alternative options to install skill-to-mcp: 1. Use `uvx` to run it immediately (requires SKILLS_DIR environment variable): ```bash SKILLS_DIR=/path/to/skills uvx skill_to_mcp ``` Or with the command-line option: ```bash uvx skill_to_mcp --skills-dir /path/to/skills ``` 2. Include it in various MCP clients that support the `mcp.json` standard: ```json { "mcpServers": { "skill-to-mcp": { "command": "uvx", "args": ["skill_to_mcp", "--skills-dir", "/path/to/your/skills"], "env": { "UV_PYTHON": "3.12" } } } } ``` 3. Install it through `pip`: ```bash pip install --user skill_to_mcp ``` 4. Install the latest development version: ```bash pip install git+https://github.com/biocontext-ai/skill-to-mcp.git@main ``` ## Deployment Options ### Local Development For development and testing: ```bash # Using uvx (recommended) SKILLS_DIR=/path/to/skills uvx skill_to_mcp # Using pip pip install skill_to_mcp skill_to_mcp --skills-dir /path/to/skills ``` ### Production Deployment For production environments with HTTP transport: ```bash export MCP_ENVIRONMENT=PRODUCTION export SKILLS_DIR=/path/to/skills export MCP_TRANSPORT=http export MCP_PORT=8000 skill_to_mcp ``` ### Docker Deployment Create a `Dockerfile`: ```dockerfile FROM python:3.12-slim WORKDIR /app RUN pip install skill_to_mcp COPY skills /app/skills ENV SKILLS_DIR=/app/skills ENV MCP_TRANSPORT=http ENV MCP_PORT=8000 CMD ["skill_to_mcp"] ``` Build and run: ```bash docker build -t skill-to-mcp . docker run -p 8000:8000 skill-to-mcp ``` ## About BioContextAI [BioContextAI](https://biocontext.ai) is a community effort to connect agentic artificial intelligence with biomedical resources using the Model Context Protocol. The [Registry](https://biocontext.ai/registry) is a community-driven catalog of MCP servers for biomedical research, enabling researchers and developers to discover, access, and contribute specialized tools and databases. **Key Principles:** - **FAIR4RS Compliant**: Findable, Accessible, Interoperable, Reusable for Research Software - **Community-Driven**: Open-source and collaborative development - **Standardized**: Built on the Model Context Protocol specification ## Contributing Contributions are welcome! See [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines on: - Development setup - Code style requirements - Testing procedures - Pull request process To contribute skills to the biomedical community, consider adding them to the [BioContextAI Registry](https://biocontext.ai/registry). ## Contact If you found a bug, please use the [issue tracker][]. For questions about BioContextAI or the registry, visit [biocontext.ai](https://biocontext.ai). ## Citation If you use this software in your research, please cite the BioContextAI paper: ```bibtex @article{BioContext_AI_Kuehl_Schaub_2025, title={BioContextAI is a community hub for agentic biomedical systems}, url={http://dx.doi.org/10.1038/s41587-025-02900-9}, urldate = {2025-11-06}, doi={10.1038/s41587-025-02900-9}, year = {2025}, month = nov, journal={Nature Biotechnology}, publisher={Springer Science and Business Media LLC}, author={Kuehl, Malte and Schaub, Darius P. and Carli, Francesco and Heumos, Lukas and Hellmig, Malte and Fernández-Zapata, Camila and Kaiser, Nico and Schaul, Jonathan and Kulaga, Anton and Usanov, Nikolay and Koutrouli, Mikaela and Ergen, Can and Palla, Giovanni and Krebs, Christian F. and Panzer, Ulf and Bonn, Stefan and Lobentanzer, Sebastian and Saez-Rodriguez, Julio and Puelles, Victor G.}, year={2025}, month=nov, language={en}, } ``` ## Acknowledgments - **Example Skill**: The included `single-cell-rna-qc` skill is adapted from [Anthropic's Life Sciences repository](https://github.com/anthropics/life-sciences) - **Anthropic**: For developing Claude Skills and the Model Context Protocol - **scverse®**: The scverse community ([scverse.org](https://scverse.org)) for best practices in single-cell analysis - **BioContextAI Community**: For fostering open-source biomedical AI infrastructure ## License This project is licensed under the Apache License 2.0 - see the [LICENSE](LICENSE) file for details. **Note**: While this software is open-source, individual skills may have their own licenses. Users are responsible for compliance with the licenses of any skills they use or distribute. [uv]: https://github.com/astral-sh/uv [issue tracker]: https://github.com/biocontext-ai/skill-to-mcp/issues [tests]: https://github.com/biocontext-ai/skill-to-mcp/actions/workflows/test.yaml [documentation]: https://skill-to-mcp.readthedocs.io [changelog]: https://skill-to-mcp.readthedocs.io/en/latest/changelog.html [api documentation]: https://skill-to-mcp.readthedocs.io/en/latest/api.html [pypi]: https://pypi.org/project/skill-to-mcp [registry]: https://biocontext.ai/registry [source]: https://github.com/biocontext-ai/skill-to-mcp