ToolHive GitHub Actions

GitHub Actions for installing and running ToolHive, a tool for managing Model Context Protocol (MCP) servers.

🚀 Quick Start

Install ToolHive

- name: Install ToolHive
  uses: StacklokLabs/toolhive-actions/install@v0
  with:
    version: latest  # or specify a version like 'v0.2.5'

Run an MCP Server

- name: Run Fetch MCP Server
  uses: stackloklabs/toolhive-actions/run-mcp-server@v0
  with:
    server: fetch

📦 Available Actions

1. install - Install ToolHive CLI

Installs the ToolHive CLI (thv) on your GitHub Actions runner.

Features:

• 🔍 Auto-detects OS and architecture
• 📌 Supports specific version installation
• ✅ Checksum verification for security
• 🚀 Caching for faster subsequent runs
• 🖥️ Cross-platform support (Linux, macOS, Windows)

📖 Full Documentation

2. run-mcp-server - Run MCP Servers

Runs MCP servers using the installed ToolHive CLI.

Features:

• 📦 Run servers from ToolHive registry
• 🐳 Support for Docker images
• 🔧 Protocol schemes (uvx://, npx://, go://)
• 🔐 Secret management
• 📁 Volume mounting
• 🌐 Network isolation
• 🛠️ Tool filtering

📖 Full Documentation

3. mcp-config - Save MCP Configuration

Persists MCP server configurations to a file and optionally uploads as an artifact.

Features:

• 💾 Save MCP server configurations
• 📤 Upload as GitHub Actions artifact
• 🏷️ Filter servers by labels
• 📊 JSON format output

📖 Full Documentation

4. skill-build - Build ToolHive Skills

Build and optionally push a ToolHive skill as an OCI artifact.

Features:

• 🏗️ Build skills from a local directory containing SKILL.md
• 🏷️ Build multiple complete OCI references in input order
• 📤 Push every built artifact to any OCI-compatible registry (ghcr.io, Docker Hub, etc.)
• ✅ Validates skill structure and rejects conflicting or duplicate references

Use the newline-delimited tags input for one or more references:

- name: Build versioned skill artifacts
  id: skill
  uses: StacklokLabs/toolhive-actions/skill-build@v0
  with:
    path: ./my-skill
    tags: |
      ghcr.io/example/my-skill:v1.2.3
      ghcr.io/example/my-skill:latest
    push: 'true'

Each explicit reference is built separately because ToolHive accepts one --tag per build; artifact digests may differ. Blank lines are ignored, whitespace is trimmed, order is preserved, and duplicates are rejected. The reference output is the first built reference and references contains all references, newline-delimited. The legacy single-reference tag input is deprecated and warns when used; it cannot be combined with tags. With neither input, ToolHive's default reference is preserved. See the full documentation for migration details and output usage.

📖 Full Documentation

5. ai-plugin-build - Build AI-Tool Plugins

Build, validate, and optionally publish signed AI-tool plugins as OCI artifacts. Supports ordered newline-delimited references and ToolHive's default reference behavior.

📖 Full Documentation

📚 Examples

Basic Installation and Usage

name: Use ToolHive
on: [push]

jobs:
  example:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      
      - name: Install ToolHive
        uses: StacklokLabs/toolhive-actions/install@v0
        
      - name: Run Fetch Server
        uses: StacklokLabs/toolhive-actions/run-mcp-server@v0
        with:
          server: fetch
          
      - name: Use the MCP Server
        run: |
          # Your code that uses the MCP server
          echo "Server is running at ${{ steps.run-server.outputs.url }}"

Advanced Usage with Secrets

- name: Run GitHub MCP Server
  uses: stackloklabs/toolhive-actions/run-mcp-server@v0
  with:
    server: github
    secrets: |
      {
        "GITHUB_PERSONAL_ACCESS_TOKEN": "${{ secrets.GITHUB_TOKEN }}"
      }

Using Docker Images

- name: Run Custom MCP Server
  uses: StacklokLabs/toolhive-actions/run-mcp-server@v0
  with:
    server: my-org/my-mcp-server:latest
    transport: sse
    proxy-port: 8080

Using Protocol Schemes

- name: Run Python MCP Server
  uses: stackloklabs/toolhive-actions/run-mcp-server@v0
  with:
    server: uvx://my-python-mcp-server@latest
    volumes: |
      ./data:/app/data

🎯 Use Cases

• AI-Powered CI/CD: Integrate MCP servers into your workflows for AI-assisted tasks
• Documentation Generation: Use MCP servers to generate or update documentation
• Code Analysis: Run MCP servers for advanced code analysis and suggestions
• Testing: Use MCP servers in your test suites for AI-powered testing
• Automation: Automate complex tasks with MCP server capabilities

🔧 Requirements

• GitHub Actions runner (ubuntu-latest, macos-latest, or windows-latest)
• Docker or Podman (for running MCP servers on Linux)
• GitHub token (automatically provided in Actions)

📊 Compatibility Matrix

Runner OS	Architecture	Install	Run Server	Notes
Ubuntu	amd64	✅	✅	Fully supported
Ubuntu	arm64	✅	✅	Fully supported
macOS	amd64	✅	⚠️	See #3
macOS	arm64	✅	⚠️	See #3
Windows	amd64	⚠️	✅	See #2
Windows	arm64	⚠️	✅	See #2

⚠️ Known Issues

Windows: PowerShell PATH Issue (#2)

The thv command may not be recognized in PowerShell after installation. Workarounds:

• Use shell: bash in your workflow steps
• Reference the full path: ${{ steps.install.outputs.path }}

macOS: Container Runtime Not Available (#3)

ToolHive cannot run MCP servers on macOS runners due to missing container runtime. Workarounds:

• Use Linux runners for running MCP servers
• Use macOS only for installation testing

For the latest status and updates on these issues, please check the issues page.

🔒 Security

• All downloads are verified using checksums
• Runs with minimal required permissions
• Secrets are handled securely
• Network isolation available for enhanced security

📝 Versioning

We use semantic versioning and maintain major version tags:

• @v0 - Latest v0.x.x release (recommended for stability)
• @v0.0.2 - Specific version
• @main - Latest development version (not recommended for production)

🤝 Contributing

We welcome contributions! Please see our Contributing Guide for details.

Development Setup

# Clone the repository
git clone https://github.com/StacklokLabs/toolhive-actions.git
cd toolhive-actions

# Test the actions locally using act (https://github.com/nektos/act)
act -W .github/workflows/test.yml

# Or push to a branch and let GitHub Actions run the tests
git checkout -b test-branch
git push origin test-branch

Testing in Your Own Workflow

To test these actions in your own repository:

name: Test ToolHive Actions
on: [push, pull_request]

jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      
      - name: Install ToolHive
        uses: StacklokLabs/toolhive-actions/install@v0
        
      - name: Verify installation
        run: thv version

📄 License

This project is licensed under the Apache License 2.0 - see the LICENSE file for details.

🔗 Related Projects

• ToolHive - The main ToolHive project
• ToolHive Documentation - Official documentation
• MCP Specification - Model Context Protocol specification

💬 Support

• GitHub Issues - Bug reports and feature requests
• Discord - Community support and discussions
• Documentation - Official ToolHive documentation