Running MCP Servers Directly from GitHub

I’ve been setting up MCP servers for Claude Code, and I hit a common problem: the server I wanted wasn’t on npm.

Most MCP documentation assumes you’ll run npx @some/package. But what if the package only exists on GitHub? Turns out, npx handles this natively.

The Syntax

npx --yes github:<user>/<repo> <bin-name>

That’s it. npx will clone the repo, run npm install, build it (if there’s a prepare script), and execute the binary.

A Real Example

I wanted to use fastmail-mcp—a TypeScript MCP server for Fastmail’s JMAP API. It’s not on npm. Here’s how I configured it for Claude Code.

In your .mcp.json:

{
  "mcpServers": {
    "fastmail": {
      "command": "npx",
      "args": [
        "--yes",
        "github:MadLlama25/fastmail-mcp",
        "fastmail-mcp"
      ],
      "env": {
        "FASTMAIL_API_TOKEN": "your-token-here"
      }
    }
  }
}

The --yes flag auto-confirms the install prompt. The last argument (fastmail-mcp) is the binary name defined in the package’s bin field.

Pinning to a Version

Running from main is fine for testing, but for stability you’ll want to pin to a release:

{
  "args": [
    "--yes",
    "github:MadLlama25/[email protected]",
    "fastmail-mcp"
  ]
}

What Makes This Work

For a GitHub repo to work with npx github:, it needs two things in package.json:

{
  "name": "fastmail-mcp",
  "bin": {
    "fastmail-mcp": "dist/index.js"
  },
  "scripts": {
    "prepare": "npm run build"
  }
}

The bin field defines the executable name. The prepare script ensures the TypeScript compiles when npx installs from source.

Python Packages Too

The same pattern works for Python MCP servers using uvx:

{
  "command": "uvx",
  "args": [
    "--from",
    "git+https://github.com/user/repo",
    "package-name"
  ]
}

Why This Matters

The MCP ecosystem is young. Many useful servers exist only as GitHub repos—personal projects, experiments, or tools that haven’t been published yet. Knowing how to run them directly means you’re not limited to what’s on npm.

Next time you find an interesting MCP server on GitHub, you don’t have to wait for it to be published. Just point npx at it and go.