Skip to content
Back to search

mcp-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,…

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
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/captaincrouton89--mcp-boilerplate/badge.svg)](/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)

  1. # MCP Server Boilerplate
  2. 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.
  3. ## Purpose
  4. This boilerplate helps you quickly start building:
  5. - Custom tools for AI assistants
  6. - Resource providers for dynamic content
  7. - Prompt templates for common operations
  8. - Integration points for external APIs and services
  9. ## Features
  10. - Two example tools: "hello-world" and "get-mcp-docs"
  11. - TypeScript support with ES2022 target and ES modules
  12. - Multi-client installation scripts (Claude Desktop, Cursor, Claude Code, Gemini, etc.)
  13. - Automatic npm publishing workflow
  14. - Environment variable support via `.env.local`
  15. - Clean project structure with Zod validation
  16. ## How It Works
  17. This MCP server template provides:
  18. 1. A basic server setup using the MCP SDK
  19. 2. Example tool implementation
  20. 3. Build and installation scripts
  21. 4. TypeScript configuration for development
  22. The included example demonstrates how to create a simple tool that takes a name parameter and returns a greeting.
  23. ## Getting Started
  24. ### Option 1: Use the Published Package (Recommended)
  25. You can use this MCP server directly without cloning:
  26. ```bash
  27. # Run the server directly with npx
  28. npx @r-mcp/boilerplate
  29. ```
  30. ### Option 2: Customize and Develop
  31. ```bash
  32. # Clone the boilerplate
  33. git clone <your-repo-url>
  34. cd mcp-server-boilerplate
  35. # Install dependencies
  36. pnpm install
  37. # Build the project
  38. pnpm run build
  39. # Start the server
  40. pnpm start
  41. ```
  42. ## Installation Scripts
  43. This boilerplate includes convenient installation scripts for different MCP clients:
  44. ```bash
  45. # Install to all MCP clients (Claude Desktop, Cursor, Claude Code, Gemini, MCP)
  46. pnpm run install-server
  47. # Install to specific clients
  48. pnpm run install-desktop # Claude Desktop
  49. pnpm run install-cursor # Cursor IDE
  50. pnpm run install-code # Claude Code CLI
  51. pnpm run install-code-library # Claude Code Library (~/.claude/mcp-library/)
  52. pnpm run install-mcp # Local .mcp.json for development
  53. # You can also combine multiple targets:
  54. node scripts/update-config.js cursor code desktop
  55. ```
  56. These scripts will:
  57. - Build the project automatically (TypeScript compilation + chmod permissions)
  58. - Configure clients to use `npx @r-mcp/<directory-name>@latest` (auto-updating)
  59. - Only the local `.mcp.json` uses the development version (`node dist/index.js`)
  60. - Include environment variables from `.env.local` if present
  61. ## Publishing Your Server
  62. To publish your customized MCP server:
  63. ```bash
  64. # Build, commit, and publish to npm in one command
  65. pnpm run release
  66. ```
  67. This script (`scripts/build-and-publish.js`) will:
  68. 1. Commit any pending changes first
  69. 2. Update package name to `@r-mcp/<directory-name>`
  70. 3. Update bin name to match directory
  71. 4. Increment patch version automatically
  72. 5. Build the TypeScript project
  73. 6. Commit version bump to git
  74. 7. Push to remote repository
  75. 8. Publish to npm with public access
  76. ## Usage with MCP Clients
  77. The installation scripts automatically configure your MCP clients. For reference, here's what gets added:
  78. ### Production Clients (Claude Desktop, Cursor, Claude Code, Gemini):
  79. ```json
  80. {
  81. "mcpServers": {
  82. "boilerplate": {
  83. "command": "npx",
  84. "args": ["-y", "@r-mcp/boilerplate@latest"],
  85. "env": {
  86. // Environment variables from .env.local are included here
  87. }
  88. }
  89. }
  90. }
  91. ```
  92. ### Local Development (`.mcp.json`):
  93. ```json
  94. {
  95. "mcpServers": {
  96. "boilerplate": {
  97. "command": "node",
  98. "args": ["/absolute/path/to/dist/index.js"],
  99. "env": {
  100. // Environment variables from .env.local are included here
  101. }
  102. }
  103. }
  104. }
  105. ```
  106. After running installation scripts, restart your MCP client to connect to the server.
  107. ## Customizing Your Server
  108. ### Adding Tools
  109. Tools are functions that the AI assistant can call. Here's the basic structure:
  110. ```typescript
  111. server.tool(
  112. "tool-name",
  113. "Description of what the tool does",
  114. {
  115. // Zod schema for parameters
  116. param1: z.string().describe("Description of parameter"),
  117. param2: z.number().optional().describe("Optional parameter"),
  118. },
  119. async ({ param1, param2 }) => {
  120. // Your tool logic here
  121. return {
  122. content: [
  123. {
  124. type: "text",
  125. text: "Your response",
  126. },
  127. ],
  128. };
  129. }
  130. );
  131. ```
  132. ### Adding Resources
  133. Resources provide dynamic content that the AI can access:
  134. ```typescript
  135. server.resource(
  136. "resource://example/{id}",
  137. "Description of the resource",
  138. async (uri) => {
  139. // Extract parameters from URI
  140. const id = uri.path.split("/").pop();
  141. return {
  142. contents: [
  143. {
  144. uri,
  145. mimeType: "text/plain",
  146. text: `Content for ${id}`,
  147. },
  148. ],
  149. };
  150. }
  151. );
  152. ```
  153. ### Adding Prompts
  154. Prompts are reusable templates:
  155. ```typescript
  156. server.prompt(
  157. "prompt-name",
  158. "Description of the prompt",
  159. {
  160. // Parameters for the prompt
  161. topic: z.string().describe("The topic to discuss"),
  162. },
  163. async ({ topic }) => {
  164. return {
  165. description: `A prompt about ${topic}`,
  166. messages: [
  167. {
  168. role: "user",
  169. content: {
  170. type: "text",
  171. text: `Please help me with ${topic}`,
  172. },
  173. },
  174. ],
  175. };
  176. }
  177. );
  178. ```
  179. ## Project Structure
  180. ```
  181. ├── src/
  182. │ └── index.ts # Main MCP server implementation
  183. ├── scripts/
  184. │ ├── update-config.js # Multi-client configuration installer
  185. │ └── build-and-publish.js # Automated npm publishing workflow
  186. ├── dist/ # Compiled JavaScript (generated)
  187. ├── package.json # Project configuration
  188. ├── tsconfig.json # TypeScript configuration
  189. ├── CLAUDE.md # Claude Code instructions
  190. ├── .env.local # Environment variables (optional)
  191. └── README.md # This file
  192. ```
  193. ## Development Workflow
  194. ### Local Development
  195. 1. Make changes to `src/index.ts`
  196. 2. Run `pnpm run build` to compile TypeScript
  197. 3. Test your server with `pnpm start`
  198. 4. Use `pnpm run install-mcp` for local testing
  199. 5. Restart your MCP client to load changes
  200. ### Publishing Updates
  201. 1. Test your changes locally
  202. 2. Run `pnpm run release` to publish to npm
  203. 3. Clients using `npx @r-mcp/<your-package>@latest` auto-update
  204. 4. No client reconfiguration needed
  205. ## Environment Variables
  206. Create a `.env.local` file for environment-specific configuration:
  207. ```bash
  208. # .env.local
  209. API_KEY=your-api-key
  210. DATABASE_URL=your-database-url
  211. ```
  212. These variables are automatically included in MCP server configurations during installation.
  213. ## Next Steps
  214. 1. Fork or clone this boilerplate
  215. 2. Customize the server name and tools in `src/index.ts`
  216. 3. Add your own tools, resources, and prompts
  217. 4. Configure environment variables in `.env.local`
  218. 5. Run `pnpm run release` to publish your server
  219. 6. Install to clients with `pnpm run install-server`
  220. ## License
  221. MIT

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.