Skip to main content
Glama
BoosClues

MCP Server Boilerplate

by BoosClues
OverviewSchemaRelated ServersScoreDiscussions
JavaScript

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

Related MCP server: MCP Server Boilerplate

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:

  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

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:

  1. Commit any pending changes first

  2. Update package name to @r-mcp/<directory-name>

  3. Update bin name to match directory

  4. Increment patch version automatically

  5. Build the TypeScript project

  6. Commit version bump to git

  7. Push to remote repository

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

  1. Make changes to src/index.ts

  2. Run pnpm run build to compile TypeScript

  3. Test your server with pnpm start

  4. Use pnpm run install-mcp for local testing

  5. Restart your MCP client to load changes

Publishing Updates

  1. Test your changes locally

  2. Run pnpm run release to publish to npm

  3. Clients using npx @r-mcp/<your-package>@latest auto-update

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

  1. Fork or clone this boilerplate

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

  3. Add your own tools, resources, and prompts

  4. Configure environment variables in .env.local

  5. Run pnpm run release to publish your server

  6. Install to clients with pnpm run install-server

License

MIT

Available Tools

2 tools
get-mcp-docsD

Make an MCP server

ParametersJSON Schema
NameRequiredDescriptionDefault
nameYesThe name of the MCP server

TDQS

D1.7/5.0
Behavior1/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations are provided, so the description carries the full burden of behavioral disclosure. The description 'Make an MCP server' doesn't reveal any behavioral traits - it doesn't specify whether this is a read or write operation, what permissions are needed, whether it's idempotent, what happens on success/failure, or any side effects. For a tool with zero annotation coverage, this is completely inadequate.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness2/5

Is the description appropriately sized, front-loaded, and free of redundancy?

While the description is technically concise with just three words, it's under-specified rather than efficiently informative. The single sentence doesn't earn its place by providing meaningful information - it's too brief to be helpful. Good conciseness balances brevity with completeness, which this description fails to achieve.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness1/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given that this is a single-parameter tool with no annotations and no output schema, the description is completely inadequate. It doesn't explain what 'making an MCP server' entails, what the tool actually does, what it returns, or how to interpret results. For even a simple tool, this level of incompleteness makes it unusable without additional context.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The input schema has 100% description coverage with a single parameter 'name' clearly documented as 'The name of the MCP server'. The description doesn't add any additional meaning beyond what the schema provides. With complete schema coverage, the baseline score of 3 is appropriate since the schema does all the parameter documentation work.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose2/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description 'Make an MCP server' is a tautology that essentially restates the tool name 'get-mcp-docs' in different words. It doesn't specify what 'make' means in this context (create, generate, fetch, etc.) or what 'MCP server' refers to. While it includes a verb+resource, it's too vague to distinguish from the sibling 'hello-world' tool or understand the actual purpose.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines1/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description provides no guidance on when to use this tool versus alternatives. There's no mention of context, prerequisites, or comparison to the sibling 'hello-world' tool. It doesn't indicate what scenarios would require 'making an MCP server' or what the expected outcome should be.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

hello-worldB

Say hello to the user

ParametersJSON Schema
NameRequiredDescriptionDefault
nameYesThe name of the user

TDQS

B3.1/5.0
Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations provided, the description carries the full burden of behavioral disclosure. 'Say hello' implies a read-only, non-destructive action, but it doesn't specify output format, side effects, or any behavioral traits like error handling or performance characteristics. This is a significant gap for a tool with zero annotation coverage.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is extremely concise with a single sentence ('Say hello to the user') that directly states the tool's purpose. It's front-loaded with zero waste, making it easy for an agent to parse quickly.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness3/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the tool's simplicity (one parameter, no output schema, no annotations), the description is minimally adequate. It states what the tool does but lacks details on behavioral context, usage guidelines, or output expectations, which are important even for simple tools to ensure correct invocation.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The description adds no parameter semantics beyond what the input schema provides. With 100% schema description coverage (the 'name' parameter is fully documented in the schema), the baseline score is 3. The description doesn't compensate with additional context about parameter usage or constraints.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description 'Say hello to the user' clearly states the tool's action (say hello) and target (the user), providing a specific verb+resource. However, it doesn't explicitly differentiate from its sibling tool 'get-mcp-docs', which appears unrelated but could benefit from clearer distinction in a broader context.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description provides no guidance on when to use this tool versus alternatives. There's no mention of context, prerequisites, or exclusions, leaving the agent to infer usage based solely on the tool name and purpose.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Install Server
RayrunBuild, deploy, and operate MCP servers without becoming an infrastructure team.ray.runAd

TDQS

C2.2/5.0
Disambiguation5/5

The two tools have completely distinct purposes: 'get-mcp-docs' is for server creation/development, while 'hello-world' is for user interaction. There is no overlap or ambiguity between them, making it easy for an agent to select the correct tool based on the task.

Naming Consistency2/5

The naming is inconsistent: 'get-mcp-docs' uses kebab-case with a verb-object structure, while 'hello-world' uses kebab-case but is a phrase rather than a clear action. There is no predictable pattern across the tools, making the set chaotic and hard to interpret systematically.

Tool Count2/5

With only 2 tools, this server feels thin for a 'boilerplate' purpose, which typically implies a foundational or example set. The count is too low to adequately cover even basic MCP server operations, suggesting an incomplete or minimal implementation.

Completeness1/5

The server is severely incomplete for a boilerplate domain: it lacks essential tools for MCP server development (e.g., configuration, testing, deployment) and only includes a trivial 'hello-world' tool. There are significant gaps that would prevent agents from performing meaningful tasks.

Maintenance

ActivityInactive
ResponsivenessNo issues

Resources

Unclaimed servers have limited discoverability.

Looking for Admin?

If you are the server author, to access and configure the admin panel.

Related MCP Connectors

Related MCP Servers

  • MCP Server Boilerplate

    luquitared
    F
    license
    C
    quality
    D
    maintenance
    A starter template for building MCP servers that can integrate with Claude, Cursor, or other MCP-compatible AI assistants to create custom tools, resource providers, and prompt templates.
    2
    0

  • MCP Server Boilerplate

    CaptainCrouton89
    F
    license
    A
    quality
    D
    maintenance
    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.
    7
    16

  • MCP Server Boilerplate

    BoosClues
    F
    license
    Not graded
    quality
    D
    maintenance
    A starter template for building MCP servers with TypeScript support, example tools, and automated installation scripts for Claude Desktop, Cursor, and other MCP-compatible AI assistants. Provides a foundation for creating custom tools, resource providers, and prompt templates.
    16

  • MCP Server Boilerplate

    ricleedo
    F
    license
    B
    quality
    D
    maintenance
    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 quickly create their own MCP integrations.
    1
    21

Latest Blog Posts

MCP directory API

We provide all the information about MCP servers via our MCP API.

curl -X GET 'https://glama.ai/api/mcp/v1/servers/BoosClues/new-MCP-builder'

If you have feedback or need assistance with the MCP directory API, please join our Discord server