Skip to main content
Glama

Quickstart: Publish an MCP Server to the MCP Registry

Written by on .

mcp
official reference mirror
  1. Prerequisites
    1. Step 1: Add verification information to the package
      1. Step 2: Publish the package
        1. Step 3: Install mcp-publisher
          1. Step 4: Create server.json
            1. Step 5: Authenticate with the MCP Registry
              1. Step 6: Publish to the MCP Registry
                1. Troubleshooting

                  This tutorial will show you how to publish an MCP server written in TypeScript to the MCP Registry using the official mcp-publisher CLI tool.

                  NOTE

                  This document is a mirror of theofficial reference.

                  Prerequisites

                  • Node.js — This tutorial assumes the MCP server is written in TypeScript.

                  • npm account — The MCP Registry only hosts metadata, not artifacts. Before publishing to the MCP Registry, we will publish the MCP server's package to npm, so you will need an npm account.

                  • GitHub account — The MCP Registry supports multiple authentication methods. For simplicity, this tutorial will use GitHub-based authentication, so you will need a GitHub account.

                  If you do not have an MCP server written in TypeScript, you can copy the weather-server-typescript server from the modelcontextprotocol/quickstart-resources to follow along with this tutorial:

                  git clone --depth 1 git@github.com:modelcontextprotocol/quickstart-resources.git cp -r quickstart-resources/weather-server-typescript . rm -rf quickstart-resources cd weather-server-typescript

                  And edit package.json to reflect your information:

                  { - "name": "mcp-quickstart-ts", - "version": "1.0.0", + "name": "@my-username/mcp-weather-server", + "version": "1.0.1", "main": "index.js",
                  "license": "ISC", - "description": "", + "repository": { + "type": "git", + "url": "https://github.com/my-username/mcp-weather-server.git" + }, + "description": "An MCP server for weather information.", "devDependencies": {

                  Step 1: Add verification information to the package

                  The MCP Registry verifies that a server's underlying package matches its metadata. For npm packages, this requires adding an mcpName property to package.json:

                  { "name": "@my-username/mcp-weather-server", "version": "1.0.1", + "mcpName": "io.github.my-username/weather", "main": "index.js",

                  The value of mcpName will be your server's name in the MCP Registry.

                  Because we will be using GitHub-based authentication, mcpName must start with io.github.my-username/.

                  Step 2: Publish the package

                  The MCP Registry only hosts metadata, not artifacts, so we must publish the package to npm before publishing the server to the MCP Registry.

                  Ensure the distribution files are built:

                  # Navigate to project directory cd weather-server-typescript # Install dependencies npm install # Build the distribution files npm run build

                  Then follow npm's publishing guide. In particular, you will probably need to run the following commands:

                  # If necessary, authenticate to npm npm adduser # Publish the package npm publish --access public

                  You can verify your package is published by visiting its npm URL, such as https://www.npmjs.com/package/@my-username/mcp-weather-server.

                  Step 3: Install mcp-publisher

                  Install the mcp-publisher CLI tool using a pre-built binary or Homebrew:

                  curl -L "https://github.com/modelcontextprotocol/registry/releases/latest/download/mcp-publisher_$(uname -s | tr '[:upper:]' '[:lower:]')_$(uname -m | sed 's/x86_64/amd64/;s/aarch64/arm64/').tar.gz" | tar xz mcp-publisher && sudo mv mcp-publisher /usr/local/bin/
                  $arch = if ([System.Runtime.InteropServices.RuntimeInformation]::ProcessArchitecture -eq "Arm64") { "arm64" } else { "amd64" }; Invoke-WebRequest -Uri "https://github.com/modelcontextprotocol/registry/releases/latest/download/mcp-publisher_windows_$arch.tar.gz" -OutFile "mcp-publisher.tar.gz"; tar xf mcp-publisher.tar.gz mcp-publisher.exe; rm mcp-publisher.tar.gz # Move mcp-publisher.exe to a directory in your PATH
                  brew install mcp-publisher

                  Verify that mcp-publisher is correctly installed by running:

                  mcp-publisher --help

                  You should see output like:

                  MCP Registry Publisher Tool Usage: mcp-publisher <command> [arguments] Commands: init Create a server.json file template login Authenticate with the registry logout Clear saved authentication publish Publish server.json to the registry

                  Step 4: Create server.json

                  The mcp-publisher init command can generate a server.json template file with some information derived from your project.

                  In your server project directory, run mcp-publisher init:

                  mcp-publisher init

                  Open the generated server.json file, and you should see contents like:

                  { "$schema": "https://static.modelcontextprotocol.io/schemas/2025-12-11/server.schema.json", "name": "io.github.my-username/weather", "description": "An MCP server for weather information.", "repository": { "url": "https://github.com/my-username/mcp-weather-server", "source": "github" }, "version": "1.0.0", "packages": [ { "registryType": "npm", "identifier": "@my-username/mcp-weather-server", "version": "1.0.0", "transport": { "type": "stdio" }, "environmentVariables": [ { "description": "Your API key for the service", "isRequired": true, "format": "string", "isSecret": true, "name": "YOUR_API_KEY" } ] } ] }

                  Edit the contents as necessary:

                  { "$schema": "https://static.modelcontextprotocol.io/schemas/2025-12-11/server.schema.json", "name": "io.github.my-username/weather", "description": "An MCP server for weather information.", "repository": { "url": "https://github.com/my-username/mcp-weather-server", "source": "github" }, - "version": "1.0.0", + "version": "1.0.1", "packages": [ { "registryType": "npm", "identifier": "@my-username/mcp-weather-server", - "version": "1.0.0", + "version": "1.0.1", "transport": { "type": "stdio" - }, - "environmentVariables": [ - { - "description": "Your API key for the service", - "isRequired": true, - "format": "string", - "isSecret": true, - "name": "YOUR_API_KEY" - } - ] + } } ] }

                  The name property in server.json must match the mcpName property in package.json.

                  Step 5: Authenticate with the MCP Registry

                  For this tutorial, we will authenticate with the MCP Registry using GitHub-based authentication.

                  Run the mcp-publisher login command to initiate authentication:

                  mcp-publisher login github

                  You should see output like:

                  Logging in with github... To authenticate, please: 1. Go to: https://github.com/login/device 2. Enter code: ABCD-1234 3. Authorize this application Waiting for authorization...

                  Visit the link, follow the prompts, and enter the authorization code that was printed in the terminal (e.g., ABCD-1234 in the above output). Once complete, go back to the terminal, and you should see output like:

                  Successfully authenticated! ✓ Successfully logged in

                  Step 6: Publish to the MCP Registry

                  Finally, publish your server to the MCP Registry using the mcp-publisher publish command:

                  mcp-publisher publish

                  You should see output like:

                  Publishing to https://registry.modelcontextprotocol.io... ✓ Successfully published ✓ Server io.github.my-username/weather version 1.0.1

                  You can verify that your server is published by searching for it using the MCP Registry API:

                  curl "https://registry.modelcontextprotocol.io/v0.1/servers?search=io.github.my-username/weather"

                  You should see your server's metadata in the search results JSON:

                  {"servers":[{ ... "name":"io.github.my-username/weather" ... }]}

                  Troubleshooting

                  Error Message

                  Action

                  "Registry validation failed for package"

                  Ensure your package includes the required validation information (e.g, mcpName property in package.json).

                  "Invalid or expired Registry JWT token"

                  Re-authenticate by running mcp-publisher login github.

                  "You do not have permission to publish this server"

                  Your authentication method doesn't match your server's namespace format. With GitHub auth, your server name must start with io.github.your-username/.

                  Written by punkpeye (@punkpeye)