MCP-Server publishen Schritt fuer Schritt

Einen MCP-Server bauen ist die eine Sache. Ihn so distributieren dass jemand anders ihn in 30 Sekunden installiert, ist die andere. Die meisten Repos bleiben in der "build" Phase haengen weil Distribution nervig wirkt. Ist sie nicht, wenn Du den Pfad einmal gemacht hast.

In diesem Playbook nehmen wir an Du hast bereits einen funktionierenden lokalen stdio-MCP-Server (Pfad: /path/to/dein-server mit package.json + src/index.ts). Du willst ihn auf npm publizieren plus auf GitHub. Am Ende kann jeder ihn mit npx -y dein-server einbinden.

1. Naming-Decision treffen

Der npm-Paket-Name muss eindeutig sein und der Pattern ist immer mcp-{thema} (mit Bindestrich, kleinbuchstaben). Beispiele die existieren: mcp-academy, mcp-academy-arena, mcp-personal-suite, mcp-multi-channel.

Suche bei npm ob Dein Name frei ist:

npm view mcp-dein-name

Wenn das 404 not found zurueckgibt, ist der Name frei. Wenn es eine Versionsnummer zeigt, suche einen anderen Namen.

Ein Tipp: Verwende kein Akronym das nur Du verstehst. mcp-cli-buddy ist besser als mcp-cb.

2. package.json aufraeumen

Das hier sind die Pflicht-Felder fuer ein veroeffentlichtes MCP-Paket:

{
  "name": "mcp-dein-name",
  "version": "0.1.0",
  "description": "Ein Satz was der Server tut.",
  "license": "MIT",
  "author": "Dein Name <email>",
  "homepage": "https://github.com/deinusername/mcp-dein-name#readme",
  "repository": {
    "type": "git",
    "url": "git+https://github.com/deinusername/mcp-dein-name.git"
  },
  "bugs": "https://github.com/deinusername/mcp-dein-name/issues",
  "keywords": ["mcp", "model-context-protocol", "claude", "dein-thema"],
  "type": "module",
  "main": "dist/index.js",
  "bin": {
    "mcp-dein-name": "dist/index.js"
  },
  "files": [
    "dist/**/*",
    "README.md",
    "LICENSE"
  ],
  "engines": {
    "node": ">=20"
  },
  "scripts": {
    "build": "tsc -p tsconfig.json",
    "prepublishOnly": "npm run build"
  }
}

Das bin-Feld ist das wichtigste. Damit funktioniert npx -y mcp-dein-name ohne Install. Der prepublishOnly-Hook stellt sicher dass dist/ vor jedem npm publish neu gebaut wird.

3. Shebang in src/index.ts setzen

Damit npx Dein Script direkt ausfuehren kann, muss die erste Zeile in src/index.ts sein:

#!/usr/bin/env node

Nur das. Keine Leerzeile davor, kein Kommentar. Der Shebang muss exakt am Anfang stehen sonst funktioniert das executable nicht.

4. tsconfig auf Build-Output ausrichten

{
  "compilerOptions": {
    "target": "ES2022",
    "module": "ESNext",
    "moduleResolution": "Bundler",
    "outDir": "dist",
    "rootDir": "src",
    "declaration": true,
    "sourceMap": true,
    "strict": true,
    "esModuleInterop": true
  },
  "include": ["src/**/*"],
  "exclude": ["node_modules", "dist", "tests"]
}

Das declaration: true baut auch .d.ts Files mit. Wichtig falls jemand Dein Paket als Library nutzen will. Bei reinen MCP-Servern weniger kritisch, schadet aber nie.

5. README schreiben (drei Sektionen)

Ein gutes MCP-README hat genau drei Pflicht-Sektionen:

# mcp-dein-name

Ein Satz was es tut.

## Install

\`\`\`json
{
  "mcpServers": {
    "dein-name": {
      "command": "npx",
      "args": ["-y", "mcp-dein-name"]
    }
  }
}
\`\`\`

In Claude Desktop oder Claude Code config einfuegen, neu starten.

## Tools

- `tool_one(param)`: Was es tut
- `tool_two(param)`: Was es tut

## Beispiel-Prompts

> "Frag mcp-dein-name nach X"
> "Nutze tool_one mit Parameter Y"

Das ist alles was beim ersten Install gebraucht wird. Mehr kann hinzu, weniger nicht. Wenn jemand Deinen README liest und nicht in zwei Minuten installiert hat, ist die README zu lang.

6. Lokal mit npm pack testen

BEVOR Du publishest, simulier den Install lokal:

npm run build
npm pack
# Erzeugt mcp-dein-name-0.1.0.tgz
cd /tmp
npm install /pfad/zu/mcp-dein-name-0.1.0.tgz
ls node_modules/mcp-dein-name/dist/

Schau ob dist/index.js da ist und der Shebang oben drin steht. Wenn das fehlt, hast Du ein Build-Problem das Du jetzt fixt, nicht erst nach dem publish.

Ein Tipp: npm pack zeigt Dir die Liste der Files die in das Paket kommen. Wenn da tests/ oder .env mit drin sind, hast Du files: in package.json zu weit definiert. Korrigieren.

7. npm-Account anlegen + Login

Wenn Du noch keinen npm-Account hast: npmjs.com/signup. Dann lokal:

npm login
# Email, Passwort, OTP
npm whoami
# Sollte Deinen Username zeigen

Falls Du Two-Factor-Auth aktiviert hast (solltest Du): npm fragt nach OTP beim Login UND beim Publish. Pflicht fuer ernst gemeinte Pakete.

8. Erster Publish

npm publish --access=public

Das --access=public ist Pflicht wenn Dein Paket-Name nicht scoped ist (@org/paket). Standard ist private was bei Free-Accounts nicht geht und einen kryptischen Fehler wirft.

Verifikation:

npm view mcp-dein-name
# Zeigt jetzt 0.1.0

Plus: Im Claude-Desktop-Config einbinden und neu starten. claude mcp list muss Deinen Server zeigen.

9. GitHub-Repo + Tag

Push den Source nach GitHub:

git init
git add .
git commit -m "Initial commit: mcp-dein-name v0.1.0"
gh repo create deinusername/mcp-dein-name --public --source=. --push
git tag v0.1.0
git push --tags

Ein Release auf GitHub machen (gh release create v0.1.0 --notes "Initial release"). Das gibt Deinem Paket Diskoverbarkeit ueber GitHub-Search und macht die Versions-History fuer User nachvollziehbar.

Optional aber empfohlen: GitHub Actions fuer automatischen Publish-on-Tag mit npm provenance. Pattern findest Du in den studiomeyer-io Repos.

10. Distribution beyond npm

npm ist die Pflicht-Stelle, aber nicht die einzige. Drei weitere Plattformen wo MCP-Server gefunden werden:

• awesome-mcp-servers auf GitHub: PR aufmachen, Dein Repo unter passende Kategorie eintragen.
• MCPize Marketplace (mcpize.com): Listing eintragen, gibt Discoverability fuer Cloud-User.
• Glama (glama.ai/mcp/servers): Aggregator, freier Eintrag.

Diese drei kostenlos, einmalig 30 Minuten Arbeit, bringen die ersten User. Reddit r/ClaudeAI oder r/mcp posten ist auch wirksam falls Dein Server eine spezifische Pain loest.

Was Du nicht machen sollst: in Anfaengergruppen "Hey ich hab einen MCP-Server gebaut, schaut mal" posten. Das ist Spam und kommt nicht an. Posten geht nur wenn Du eine konkrete Use-Case-Geschichte hast.

Naechste Schritte

Nach dem ersten Publish kommt die naechste Hurde: Versions-Pflege. Patch-Releases (0.1.1) wenn Du Bugs fixt, Minor (0.2.0) bei neuen Tools, Major (1.0.0) bei API-Aenderungen. Halte Dich an SemVer, sonst frustriest Du User die Deinen Server in einem Production-Setup haben.