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, Cursor, or 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

Related MCP server: JSON MCP Boilerplate

Features

• Simple "hello-world" tool example

• TypeScript support with proper type definitions

• Easy installation scripts for different MCP clients

• Clean project structure ready for customization

How It Works

This MCP server template provides:

1. A basic server setup using the MCP SDK

2. Example tool implementation

3. Build and installation scripts

4. 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

# 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:

# For Claude Desktop
pnpm run install-desktop

# For Cursor
pnpm run install-cursor

# For Claude Code
pnpm run install-code

# Generic installation
pnpm run install-server

These scripts will build the project and automatically update the appropriate configuration files.

Usage with Claude Desktop

The installation script will automatically add the configuration, but you can also manually add it to your claude_desktop_config.json file:

{
  "mcpServers": {
    "your-server-name": {
      "command": "node",
      "args": ["/path/to/your/dist/index.js"]
    }
  }
}

Then restart Claude Desktop 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 server implementation
├── scripts/              # Installation and utility scripts
├── dist/                 # Compiled JavaScript (generated)
├── package.json          # Project configuration
├── tsconfig.json         # TypeScript configuration
└── README.md            # This file

Development

1. Make changes to src/index.ts

2. Run pnpm run build to compile

3. Test your server with pnpm start

4. Use the installation scripts to update your MCP client configuration

Next Steps

1. Update package.json with your project details

2. Customize the server name and tools in src/index.ts

3. Add your own tools, resources, and prompts

4. Integrate with external APIs or databases as needed

License

MIT