Mcpb Pack

MCPB Pack

[](https://github.com/NimbleBrainInc/mcpb-pack/actions/workflows/test.yml) [](https://opensource.org/licenses/MIT) [](https://github.com/NimbleBrainInc/mcpb-pack/releases)

A GitHub Action to package MCP servers into distributable bundles and publish them to the mpak registry.

What is this?

MCP (Model Context Protocol) is a standard for AI assistants to interact with external tools and services. An MCP server exposes tools (like "search files" or "query database") that AI assistants can call.

MCPB is a bundle format (.mcpb files) that packages an MCP server with all its dependencies into a single portable file. This makes MCP servers easy to distribute and install.

mpak is a public registry where you can publish and discover MCP bundles. Think of it like npm, but for MCP servers.

This action automates the entire workflow: build your MCP server into a bundle, attach it to your GitHub release, and register it with mpak so others can find and install it.

Quick Start

Prerequisites

Your repository needs:

1. A manifest.json describing your MCP server:

{
  "manifest_version": "0.4",
  "name": "@your-github-org/your-server",
  "version": "1.0.0",
  "description": "What your server does",
  "server": {
    "type": "python",
    "entry_point": "your_package.server",
    "mcp_config": {
      "command": "python",
      "args": ["-m", "your_package.server"]
    }
  }
}

> Note: The @scope must match your GitHub organization or username. The registry verifies this via OIDC.

1. Your MCP server code with stdio entrypoint:

# At end of server.py
if __name__ == "__main__":
    mcp.run()  # Required for mpak run / Claude Desktop

Minimal Workflow

Add this to .github/workflows/release.yml:

name: Release
on:
  release:
    types: [published]

permissions:
  contents: write
  id-token: write

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: NimbleBrainInc/mcpb-pack@v3

When you publish a GitHub release, this will:

1. Vendor all dependencies into the bundle
2. Build a .mcpb file
3. Upload it to your release
4. Register it with mpak.dev

Your server is now discoverable via mpak search and installable via mpak bundle pull.

Usage

Single Platform

For pure Python/Node servers without native dependencies:

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: NimbleBrainInc/mcpb-pack@v3

Multi-Platform

For servers with native dependencies (C extensions, Rust bindings, etc.), you need to build on each target platform:

jobs:
  build:
    strategy:
      matrix:
        include:
          - os: linux
            arch: x64
            runner: ubuntu-latest
          - os: linux
            arch: arm64
            runner: ubuntu-24.04-arm
          - os: darwin
            arch: arm64
            runner: macos-latest
          - os: darwin
            arch: x64
            runner: macos-15-intel
    runs-on: ${{ matrix.runner }}
    steps:
      - uses: actions/checkout@v4
      - uses: NimbleBrainInc/mcpb-pack@v3
        with:
          output: "{name}-{version}-${{ matrix.os }}-${{ matrix.arch }}.mcpb"

Each job builds and registers its own platform-specific bundle. The registry merges them automatically.

Runner Reference

| Platform | Runner Label | Architecture | Notes | |----------|--------------|--------------|-------| | Linux x64 | ubuntu-latest | x64 | Free | | Linux ARM | ubuntu-24.04-arm | arm64 | Free | | macOS ARM | macos-latest / macos-15 | arm64 (M1) | Free, 3 vCPU, 7 GB | | macOS Intel | macos-15-intel | x64 | Free, 4 vCPU, 14 GB |

Paid larger runners (Team/Enterprise plans):

| Platform | Runner Label | Architecture | Notes | |----------|--------------|--------------|-------| | macOS Intel | macos-15-large | x64 | 12 vCPU, 30 GB | | macOS ARM | macos-15-xlarge | arm64 (M2) | 5 vCPU + 8 GPU, 14 GB |

> Note: macos-13 is retiring December 2025. Use macos-15-intel for Intel macOS builds.

Build Only (No Publish)

For CI validation or private servers:

- uses: NimbleBrainInc/mcpb-pack@v3
  with:
    upload: false
    announce: false

Use Existing Bundle

If you already build your .mcpb bundle separately (e.g., committed to the repo or built in a prior step), you can skip the build and just upload/announce:

- uses: NimbleBrainInc/mcpb-pack@v3
  with:
    directory: packages/mcp/mcpb
    bundle-path: context7.mcpb
    build: false

This is useful when:

• Your bundle is pre-built and committed to the repository
• You have a custom build process
• You want to announce an existing bundle to mpak.dev

The action will compute the SHA256 hash and size from the provided bundle, upload it to the release, and announce it to the registry.

Cross-Platform Bundles

For pure Node.js or Python servers without native dependencies, you can announce a single bundle as cross-platform using any:

- uses: NimbleBrainInc/mcpb-pack@v3
  with:
    platform-os: any
    platform-arch: any

This registers the bundle as universal, so users on any platform can install it. The registry will serve this bundle when no platform-specific build is available.

Manual Re-announce

To re-announce an existing release (e.g., if the registry was down or you're announcing to a different registry), add workflow_dispatch to your workflow:

on:
  release:
    types: [published]
  workflow_dispatch:
    inputs:
      build:
        description: 'Build bundle'
        type: boolean
        default: true
      announce:
        description: 'Announce to registry'
        type: boolean
        default: true

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: NimbleBrainInc/mcpb-pack@v3
        with:
          build: ${{ inputs.build }}
          announce: ${{ inputs.announce }}

Then trigger manually from the Actions tab, checking out the release tag. The action uses github.ref_name as the release tag when not triggered by a release event.

> Note: The upload input only works with release events. For manual triggers, upload the bundle to the release manually or use gh release upload.

Inputs

| Input | Default | Description | | ---------------- | ------------------------------------------ | ------------------------------------------------------------- | | directory | . | Directory containing manifest.json and server code | | bundle-path | | Path to existing .mcpb bundle (use with build: false) | | output | {name}-{version}.mcpb | Output filename ({name} and {version} are replaced) | | python-version | 3.13 | Python version for vendoring (if Python server) | | build | true | Whether to build the bundle | | upload | true | Whether to upload to the GitHub release | | announce | true | Whether to register with mpak.dev | | announce-required | false | Whether announce failures should fail the workflow | | announce-url | https://registry.mpak.dev/v1/bundles/announce | Registry endpoint (change for self-hosted registries) | | platform-os | | Override detected OS (darwin, linux, win32, any) | | platform-arch | | Override detected arch (x64, arm64, any) |

Outputs

| Output | Description | | --------------- | ---------------------------------- | | bundle-path | Path to the generated .mcpb file | | bundle-size | Size of the bundle in bytes | | bundle-sha256 | SHA256 hash for integrity checks | | announced | Whether registration succeeded |

Permissions

permissions:
  contents: write   # Required to upload to releases
  id-token: write   # Required for OIDC authentication with registry

How It Works

Building

The action:

1. Validates manifest.json (mcpb v0.4 required fields, optional reverse-DNS name override)
2. Detects your server type from manifest.json (Python or Node.js)
3. Vendors all dependencies into the bundle (Python: deps/, Node: node_modules/)
4. Packages everything into a .mcpb file using the mcpb CLI

Announcing

When you announce to mpak.dev:

1. The action uploads the .mcpb bundle to the GitHub release
2. The action requests an OIDC token from GitHub
3. This token cryptographically proves the bundle came from your repository
4. The registry verifies the token and registers your bundle; the registry composes the MCP ServerDetail discovery shape from your manifest.json
5. No API keys or secrets needed

Each platform build announces its own artifact. The registry tracks all artifacts for a version, so users can install the right bundle for their system.

Opting Out of Announcing

To build without publishing to the public registry:

- uses: NimbleBrainInc/mcpb-pack@v3
  with:
    announce: false

You might want this if:

• Your server is private or internal
• You're using a self-hosted registry
• You want to test before publishing
• You distribute through other channels

MCP Registry Discovery

mpak automatically composes the MCP Registry's ServerDetail discovery shape from your bundle's manifest.json — there is no separate server.json file to maintain. Every announced bundle is reachable at:

• GET /v1/servers/ — latest ServerDetail
• GET /v1/servers//versions/ — version-specific
• GET /v1/servers/search?q=... — paginated search

Naming

By default the registry assigns a reverse-DNS name mechanically from your npm-style package name:

• @your-org/your-server → dev.mpak.your-org/your-server

If you want a branded reverse-DNS name (e.g. com.example/your-server), set it in your manifest's _meta:

{
  "manifest_version": "0.4",
  "name": "@your-org/your-server",
  "version": "1.0.0",
  "description": "What your server does",
  "_meta": {
    "dev.mpak/registry": {
      "name": "com.example/your-server"
    }
  }
}

The override must match the upstream pattern ^[a-zA-Z0-9.-]+/[a-zA-Z0-9._-]+$ (one slash separating the reverse-DNS namespace from the server name).

Migration from server.json (v2 → v3)

If you previously shipped a server.json file alongside your bundle, you can delete it. Versions of this action prior to v3 validated and uploaded server.json to the GitHub release; v3 no longer reads or uploads it. The registry composes the ServerDetail discovery shape from manifest.json instead.

git rm server.json
# Optional: add a reverse-DNS name override to manifest.json (see "Naming" above).
git add manifest.json
git commit -m "drop server.json (mcpb-pack@v3 composes registry metadata from manifest)"

Supported Runtimes

| Runtime | Detected via | Dependency vendoring | | ------- | ------------------------- | ----------------------------- | | Python | server.type: "python" | uv pip install --target | | Node.js | server.type: "node" | npm install --omit=dev | | Binary | server.type: "binary" | None (you build the binary) |

Binary Servers (Go, Rust, etc.)

For compiled languages, build your binary before running mcpb-pack:

jobs:
  build:
    strategy:
      matrix:
        include:
          - os: linux
            arch: x64
            runner: ubuntu-latest
          - os: linux
            arch: arm64
            runner: ubuntu-24.04-arm
          - os: darwin
            arch: arm64
            runner: macos-latest
          - os: darwin
            arch: x64
            runner: macos-15-intel
    runs-on: ${{ matrix.runner }}
    steps:
      - uses: actions/checkout@v4

      - uses: actions/setup-go@v5
        with:
          go-version: "1.22"

      - name: Build binary
        run: |
          mkdir -p bin
          go build -o bin/server ./cmd/server

      - uses: NimbleBrainInc/mcpb-pack@v3
        with:
          output: "{name}-{version}-${{ matrix.os }}-${{ matrix.arch }}.mcpb"

The manifest.json for binary servers:

{
  "name": "@your-org/your-server",
  "version": "1.0.0",
  "server": {
    "type": "binary",
    "entry_point": "bin/server",
    "mcp_config": {
      "command": "${__dirname}/bin/server",
      "args": []
    }
  }
}

Node.js Servers

{
  "name": "@your-org/your-server",
  "version": "1.0.0",
  "server": {
    "type": "node",
    "entry_point": "dist/index.js",
    "mcp_config": {
      "command": "node",
      "args": ["${__dirname}/dist/index.js"]
    }
  }
}

Example Repositories

• mcp-echo - Simple Python MCP server with multi-platform builds

Learn More

• MCP Documentation - Model Context Protocol specification
• mpak Registry - Browse and search published MCP bundles
• mcpb CLI - Command-line tool for building bundles locally

License

MIT

Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: NimbleBrainInc
• Source: NimbleBrainInc/mcpb-pack
• License: MIT

Install and usage instructions live in the source repository linked above.