Credits

Summary of steps from article https://dev.to/ipreda/run-your-npx-script-directly-from-github-create-your-own-cli-commands-and-other-stories-4pn3
by Iulian Preda

Goal

Setup a github repo to mimic this demo

From NPX’s Github page, we can get the following command to run in a terminal: npx github:piuccio/cowsay JavaScript FTW!.

This command installed the package in a temporary folder and run the command with the same name as the repository.

Pre-requisites

NPX is a command-line tool meant to run NPM packages containing CLI scripts.

Background

In NodeJs you have the option to create CLI commands that can be run only from NPM scripts, remember npm run <script name>?
Unless installed globally (and added to the path) they can be only called from inside a script from the scripts section in the package.json.

NPM and NPX installed

We will need NodeJs and NPX installed as a global package.
npm install -g npx.

Steps

1. prep node project files

To create awesome-command that can be used from the CLI (or using NPM).

mkdir awesome-npx-mcp  
cd awesome-npx-mcp  
npm --init

and accept the defaults or customize the inputs like name, description, license, etc.

Create the main file of the application named index.js

cat '#!/usr/bin/env node' > index.js  
cat 'console.log("Awesome npx-mcp");' >> index.js

In the package.json we will add the commands section:

"bin": {  
        "awesome-npx-mcp": "index.js",  
    }

Sidenote

If we would have installed the package locally, then we wouldn’t have been able to run awesome-command in a terminal and expect it to work. We would have had to add it to the scripts section in the package.json like this:

"scripts": {  
    "awesome": awesome-npx-mcp  
  },

and then npm run awesome or… run npx awesome-npx-mcp.

2. Make the command available over the internet without publishing package

Remember only to have one of the commands match the name of the package.

Host the package on Github in a new repository and anyone will be able to run it using npx github:<user>/<repository>. Again remember to have one of the commands in the bin section match the name of the repository.

Extra arguments we can always add them after the command name, for example
npx github:<user>/<repository> arg1 arg2.

UVX similar setup

package

For example with uvx use the git+http://.... syntax, but it always expects a package not a script.

per end of march 2025

script

uv run https://raw.githubusercontent.com/konstin/say-hi/refs/heads/main/say-hi.py

We currently don’t support this for the git protocol though.

ThirdBrAIn.tech