MCP Server Boilerplate

A starter template for building MCP (Model Context Protocol) servers. This boilerplate provides a clean foundation for creating your own MCP server that can integrate with Claude Desktop, Cursor, Claude Code, Gemini, and other MCP-compatible AI assistants.

Purpose

This boilerplate helps you quickly start building:

Custom tools for AI assistants
Resource providers for dynamic content
Prompt templates for common operations
Integration points for external APIs and services

Features

Two example tools: "hello-world" and "get-mcp-docs"
TypeScript support with ES2022 target and ES modules
Multi-client installation scripts (Claude Desktop, Cursor, Claude Code, Gemini, etc.)
Automatic npm publishing workflow
Environment variable support via .env.local
Clean project structure with Zod validation

How It Works

This MCP server template provides:

A basic server setup using the MCP SDK
Example tool implementation
Build and installation scripts
TypeScript configuration for development

The included example demonstrates how to create a simple tool that takes a name parameter and returns a greeting.

Getting Started

Option 1: Use the Published Package (Recommended)

You can use this MCP server directly without cloning:

# Run the server directly with npx
npx @r-mcp/boilerplate

Option 2: Customize and Develop

# Clone the boilerplate
git clone <your-repo-url>
cd mcp-server-boilerplate

# Install dependencies
pnpm install

# Build the project
pnpm run build

# Start the server
pnpm start

Installation Scripts

This boilerplate includes convenient installation scripts for different MCP clients:

# Install to all MCP clients (Claude Desktop, Cursor, Claude Code, Gemini, MCP)
pnpm run install-server

# Install to specific clients
pnpm run install-desktop       # Claude Desktop
pnpm run install-cursor        # Cursor IDE
pnpm run install-code          # Claude Code CLI
pnpm run install-code-library  # Claude Code Library (~/.claude/mcp-library/)
pnpm run install-mcp           # Local .mcp.json for development

# You can also combine multiple targets:
node scripts/update-config.js cursor code desktop

These scripts will:

Build the project automatically (TypeScript compilation + chmod permissions)
Configure clients to use npx @r-mcp/<directory-name>@latest (auto-updating)
Only the local .mcp.json uses the development version (node dist/index.js)
Include environment variables from .env.local if present

Publishing Your Server

To publish your customized MCP server:

# Build, commit, and publish to npm in one command
pnpm run release

This script (scripts/build-and-publish.js) will:

Commit any pending changes first
Update package name to @r-mcp/<directory-name>
Update bin name to match directory
Increment patch version automatically
Build the TypeScript project
Commit version bump to git
Push to remote repository
Publish to npm with public access

Usage with MCP Clients

The installation scripts automatically configure your MCP clients. For reference, here's what gets added:

Production Clients (Claude Desktop, Cursor, Claude Code, Gemini):

{
  "mcpServers": {
    "boilerplate": {
      "command": "npx",
      "args": ["-y", "@r-mcp/boilerplate@latest"],
      "env": {
        // Environment variables from .env.local are included here
      }
    }
  }
}

Local Development (`.mcp.json`):

{
  "mcpServers": {
    "boilerplate": {
      "command": "node",
      "args": ["/absolute/path/to/dist/index.js"],
      "env": {
        // Environment variables from .env.local are included here
      }
    }
  }
}

After running installation scripts, restart your MCP client to connect to the server.

Customizing Your Server

Adding Tools

Tools are functions that the AI assistant can call. Here's the basic structure:

server.tool(
  "tool-name",
  "Description of what the tool does",
  {
    // Zod schema for parameters
    param1: z.string().describe("Description of parameter"),
    param2: z.number().optional().describe("Optional parameter"),
  },
  async ({ param1, param2 }) => {
    // Your tool logic here
    return {
      content: [
        {
          type: "text",
          text: "Your response",
        },
      ],
    };
  }
);

Adding Resources

Resources provide dynamic content that the AI can access:

server.resource(
  "resource://example/{id}",
  "Description of the resource",
  async (uri) => {
    // Extract parameters from URI
    const id = uri.path.split("/").pop();

    return {
      contents: [
        {
          uri,
          mimeType: "text/plain",
          text: `Content for ${id}`,
        },
      ],
    };
  }
);

Adding Prompts

Prompts are reusable templates:

server.prompt(
  "prompt-name",
  "Description of the prompt",
  {
    // Parameters for the prompt
    topic: z.string().describe("The topic to discuss"),
  },
  async ({ topic }) => {
    return {
      description: `A prompt about ${topic}`,
      messages: [
        {
          role: "user",
          content: {
            type: "text",
            text: `Please help me with ${topic}`,
          },
        },
      ],
    };
  }
);

Project Structure

├── src/
│   └── index.ts              # Main MCP server implementation
├── scripts/
│   ├── update-config.js      # Multi-client configuration installer
│   └── build-and-publish.js  # Automated npm publishing workflow
├── dist/                     # Compiled JavaScript (generated)
├── package.json              # Project configuration
├── tsconfig.json             # TypeScript configuration
├── CLAUDE.md                 # Claude Code instructions
├── .env.local                # Environment variables (optional)
└── README.md                 # This file

Development Workflow

Local Development

Make changes to src/index.ts
Run pnpm run build to compile TypeScript
Test your server with pnpm start
Use pnpm run install-mcp for local testing
Restart your MCP client to load changes

Publishing Updates

Test your changes locally
Run pnpm run release to publish to npm
Clients using npx @r-mcp/<your-package>@latest auto-update
No client reconfiguration needed

Environment Variables

Create a .env.local file for environment-specific configuration:

# .env.local
API_KEY=your-api-key
DATABASE_URL=your-database-url

These variables are automatically included in MCP server configurations during installation.

Next Steps

Fork or clone this boilerplate
Customize the server name and tools in src/index.ts
Add your own tools, resources, and prompts
Configure environment variables in .env.local
Run pnpm run release to publish your server
Install to clients with pnpm run install-server

License

MIT

This server cannot be installed

security - not tested

license - not found

quality - not tested

How are these scores calculated?

remote-capable server

The server can be hosted and run remotely because it primarily relies on remote services or has no dependency on the local environment.

A starter template for building custom MCP servers that can integrate with Claude Desktop, Cursor, and other AI assistants. Provides example tools, TypeScript support, and automated publishing workflows to help developers create their own AI assistant integrations.

Related MCP Servers

MCP Server Template
hypermodel-labs
A
security
F
license
A
quality
A starter template for building Model Context Protocol servers that can be integrated with Cursor or Claude Desktop, allowing developers to create custom tools and extensions for AI assistants.
Last updated -
1
9
14
MCP Starter
instructa
A
security
A
license
A
quality
A foundation for building custom local Model Context Protocol (MCP) servers that provide tools accessible to AI assistants like Cursor or Claude Desktop.
Last updated -
1
28
MIT License
Activepieces MCP
LaunchpadAI
-
security
F
license
-
quality
An open source toolkit that converts 280+ integrations into MCP servers for use with Claude Desktop, Cursor, or Windsurf, enabling AI automation through a type-safe pieces framework written in TypeScript.
Last updated -
MCP Server Boilerplate
CaptainCrouton89
A
security
F
license
A
quality
A starter template for building Model Context Protocol servers that integrate with AI assistants like Claude and Cursor, providing custom tools, resource providers, and prompt templates.
Last updated -
2

View all related MCP servers

MCP Server Boilerplate