MCP Server Day 4: How to Publish npm Packages

🌐 Translation: Translated from Korean.

TL;DR

MCP server deployment is easier than you think:

Deploy as an npm package and run instantly with npx my-mcp-server
3 steps: Configure package.json → npm publish → Write README
Your MCP package created today can be shared with developers worldwide

What you’ll learn:

npm package structure: bin, main, files configuration
MCP server deployment: Complete npm publish process
User guide writing: How to connect with Claude Code

Structuring Your npm Package

To deploy an MCP server as an npm package, you need to configure package.json correctly. The first step in npm deployment is organizing the package structure.

Recommended Directory Structure for Deployment

Here’s the recommended directory structure for MCP package deployment:

my-first-mcp/
├── dist/                    # Build output (deployment target)
│   └── index.js             # Bundled executable
├── src/                     # Source code (development)
│   ├── index.ts             # Entry point
│   ├── tools.ts             # Tool logic
│   └── tools.test.ts        # Tests
├── package.json             # Package config (crucial!)
├── tsconfig.json            # TypeScript config
├── README.md                # User guide
├── LICENSE                  # License
└── CHANGELOG.md             # Change history

When performing npm deployment, only dist/, README.md, LICENSE, and package.json are included.

bin Configuration: CLI Executable

Configure the bin field to make the MCP server executable from the command line:

{
  "name": "my-first-mcp",
  "version": "1.0.0",
  "bin": {
    "my-first-mcp": "dist/index.js"
  }
}

With this configuration, after MCP server installation, you can run it like this:

# After global installation
npm install -g my-first-mcp
my-first-mcp  # Direct execution

# Instant execution with npx (no installation needed)
npx my-first-mcp

Important: Add a shebang at the top of dist/index.js:

#!/usr/bin/env node
// Top of dist/index.js

For TypeScript, add it to src/index.ts:

#!/usr/bin/env node
/**
 * MCP server entry point
 */
import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
// ...

files Field: Specifying Deployment Files

Explicitly specify which files to include in npm deployment:

{
  "files": [
    "dist",
    "README.md",
    "LICENSE"
  ]
}

Benefits of the files field:

Automatically excludes unnecessary files (src/, test/, node_modules/)
Minimizes npm package size
Prevents sensitive file leaks

Complete package.json

Here’s a complete package.json example for MCP server deployment:

{
  "name": "my-first-mcp",
  "version": "1.0.0",
  "description": "MCP server development tutorial - Project analysis tools",
  "type": "module",
  "main": "dist/index.js",
  "types": "dist/index.d.ts",
  "bin": {
    "my-first-mcp": "dist/index.js"
  },
  "files": [
    "dist",
    "README.md",
    "LICENSE"
  ],
  "scripts": {
    "build": "tsc",
    "prepublishOnly": "npm run build",
    "start": "node dist/index.js",
    "test": "vitest run"
  },
  "keywords": [
    "mcp",
    "model-context-protocol",
    "claude",
    "claude-code",
    "ai-tools",
    "typescript"
  ],
  "author": "Your Name &#x3C;[email protected]>",
  "license": "MIT",
  "repository": {
    "type": "git",
    "url": "git+https://github.com/username/my-first-mcp.git"
  },
  "homepage": "https://github.com/username/my-first-mcp#readme",
  "bugs": {
    "url": "https://github.com/username/my-first-mcp/issues"
  },
  "engines": {
    "node": ">=20.0.0"
  },
  "dependencies": {
    "@modelcontextprotocol/sdk": "^1.0.0",
    "zod": "^3.24.0"
  },
  "devDependencies": {
    "@types/node": "^22.0.0",
    "typescript": "^5.7.0",
    "vitest": "^2.1.0"
  }
}

Key Field Explanations

Field	Purpose	MCP Server Deployment Tips
`name`	Package name	Must be unique on npm
`version`	Version	Follow semver
`description`	Description	Summarize MCP server features
`bin`	CLI executable	Required for Claude Code connection
`files`	Deployment files	Include only dist recommended
`keywords`	Search keywords	Include mcp, claude recommended
`engines`	Node.js version	20+ recommended

prepublishOnly Script

Automatically builds before running npm publish:

{
  "scripts": {
    "prepublishOnly": "npm run build &#x26;&#x26; npm test"
  }
}

This ensures the latest build and tests always run before npm deployment.

Build Configuration

tsc vs tsup

There are two main options for TypeScript package builds:

tsc (TypeScript Compiler):

Pros: Simple configuration, no additional dependencies
Cons: Slow builds, no bundling support

tsup (esbuild-based):

Pros: Very fast, bundling support, tree shaking
Cons: Requires additional dependency

For MCP servers with simple structures, tsc is sufficient:

// tsconfig.json
{
  "compilerOptions": {
    "target": "ES2022",
    "module": "NodeNext",
    "moduleResolution": "NodeNext",
    "outDir": "./dist",
    "rootDir": "./src",
    "strict": true,
    "declaration": true,
    "esModuleInterop": true,
    "skipLibCheck": true
  },
  "include": ["src/**/*"],
  "exclude": ["node_modules", "**/*.test.ts"]
}

Build Verification

Verify build results before npm deployment:

# Build
npm run build

# Check results
ls -la dist/
# index.js
# index.d.ts (type definitions)

# Local test
node dist/index.js

npm Deployment

1. Prepare npm Account

You need an account for npm deployment:

# Create account (also possible on website)
npm adduser

# Verify login
npm whoami

2. Check Package Name Availability

Verify that your npm package name is available:

# Search for name
npm search my-first-mcp

# Or query directly
npm view my-first-mcp
# 404 error means it's available

3. Pre-deployment Testing

Test locally before npm deployment:

# Pack the package (deployment simulation)
npm pack

# Check results
tar -tzf my-first-mcp-1.0.0.tgz
# package/dist/index.js
# package/README.md
# package/LICENSE
# package/package.json

# Cleanup
rm my-first-mcp-1.0.0.tgz

4. Run npm publish

Finally, deploy with npm publish:

# Deploy
npm publish

# Success message
# + [email protected]

For public package deployment:

npm publish --access public

5. Verify Deployment

Confirm your MCP package was deployed successfully:

# Check on npm
npm view my-first-mcp

# Installation test
npx my-first-mcp

Version Management

npm package versions follow Semantic Versioning:

MAJOR.MINOR.PATCH
  │     │     └── Bug fixes
  │     └──────── New features (backward compatible)
  └────────────── Major changes (breaking changes)

Version Updates

# Patch update (1.0.0 → 1.0.1)
npm version patch

# Minor update (1.0.1 → 1.1.0)
npm version minor

# Major update (1.1.0 → 2.0.0)
npm version major

# Deploy
npm publish

Writing CHANGELOG.md

Document change history for MCP server deployment:

# Changelog

## [1.1.0] - 2024-12-03

### Added
- New Tool: analyze_structure
- Resource support added

### Fixed
- Fixed timezone calculation error

## [1.0.0] - 2024-12-01

### Added
- Initial release
- Implemented get_current_time, calculate Tools

Writing README.md

Create the README.md, the face of your npm package. It’s crucial to clearly explain MCP server installation methods.

Essential README Sections

# my-first-mcp

MCP (Model Context Protocol) Server - Project Analysis Tools

## Installation

### Instant Execution with npx

```bash
npx my-first-mcp
```

### Global Installation

```bash
npm install -g my-first-mcp
my-first-mcp
```

## Claude Code Connection

### Method 1: claude mcp add Command

```bash
claude mcp add my-first-mcp -- npx my-first-mcp
```

### Method 2: Direct Config File Edit

~/.claude/claude_desktop_config.json:

```json
{
  "mcpServers": {
    "my-first-mcp": {
      "command": "npx",
      "args": ["my-first-mcp"]
    }
  }
}
```

## Features

### Tools

| Tool | Description |
|------|-------------|
| `get_current_time` | Get current time |
| `calculate` | Basic arithmetic calculator |
| `analyze_structure` | Project structure analysis |

### Resources

| URI | Description |
|-----|-------------|
| `project://config` | Project configuration info |

## License

MIT

Adding Badges

Adding badges at the top of your README increases credibility:

[![npm version](https://badge.fury.io/js/my-first-mcp.svg)](https://www.npmjs.com/package/my-first-mcp)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
[![Node.js](https://img.shields.io/badge/Node.js-20%2B-green.svg)](https://nodejs.org/)

User Guide

Provide detailed instructions for connecting to Claude Code after MCP server installation.

Claude Code Connection (Recommended)

The easiest connection method in Claude Code:

# Add MCP server
claude mcp add my-first-mcp -- npx my-first-mcp

# Verify registration
claude mcp list

# Result
# my-first-mcp: npx my-first-mcp

Claude Desktop Connection

To use with the Claude Desktop app, edit the config file:

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
Windows: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "my-first-mcp": {
      "command": "npx",
      "args": ["my-first-mcp"]
    }
  }
}

Project-specific Configuration (.mcp.json)

Create a .mcp.json file in your project root to enable the MCP server only for that project:

{
  "mcpServers": {
    "my-first-mcp": {
      "command": "npx",
      "args": ["my-first-mcp"]
    }
  }
}

When Claude Code opens the project folder, it automatically detects the MCP package and suggests connection.

Testing the Connection

Once MCP server installation is complete, test it in Claude:

User: "What time is it now?"
Claude: [Calls get_current_time Tool]
        "The current time is Tuesday, December 3, 2024, 3:30 PM."

User: "Calculate 123 + 456"
Claude: [Calls calculate Tool]
        "123 + 456 = 579."

Deployment Checklist

Items to verify before npm deployment:

Required Items

Set name, version, description in package.json
Set executable file path in bin field
Limit deployment files with files field
Add shebang (#!/usr/bin/env node)
Complete README.md
Include LICENSE file
Pass npm test
Verify deployment files with npm pack

Summary

Key takeaways for MCP server deployment:

package.json configuration: Structure your npm package with bin, files, keywords
npm publish: Simple npm deployment in 3 steps
User guide: Clearly document Claude Code connection methods

Now your MCP package is deployed to npm, and developers worldwide can use it instantly with npx!

Next Episode Preview

Day 5: Advanced Patterns and Optimization will cover:

External API integration (GitHub API)
Caching strategies
Security considerations
Production checklist

Series Navigation

Day 1: What is MCP? Concepts and Building Your First Server
Day 2: Mastering Resources and Prompts
Day 3: Practical Project – Building a Project Analyzer MCP Server
Day 4: Deploying as an npm Package (Current)
Day 5: Advanced Patterns and Optimization (Coming Soon)