Back to search
mcp-boilerplate
MCP serverGitHub
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,…
Safety scan
A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.
Checked today
Badge for your README
Markdown
[](/listings/captaincrouton89--mcp-boilerplate)HTML
<a href="/listings/captaincrouton89--mcp-boilerplate"><img src="/api/listings/captaincrouton89--mcp-boilerplate/badge.svg" alt="findsafeskills safety rating" /></a>Install
i
Install instructions from the README
As written by the repo's author. findsafeskills has not verified these steps.
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
What was scanned
The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.
README.md · README · 279 lines
View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)
- # 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:
- 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:
- ```bash
- # Run the server directly with npx
- npx @r-mcp/boilerplate
- ```
- ### Option 2: Customize and Develop
- ```bash
- # 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:
- ```bash
- # 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:
- ```bash
- # 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):
- ```json
- {
- "mcpServers": {
- "boilerplate": {
- "command": "npx",
- "args": ["-y", "@r-mcp/boilerplate@latest"],
- "env": {
- // Environment variables from .env.local are included here
- }
- }
- }
- }
- ```
- ### Local Development (`.mcp.json`):
- ```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:
- ```typescript
- 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:
- ```typescript
- 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:
- ```typescript
- 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:
- ```bash
- # .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
Ratings and comments
Sign in to rate this skill.
Sign inFree to use. If it’s helped, pass it on.