boilerplate

TypeScript Model Context Protocol (MCP) server boilerplate providing IP lookup tools/resources. Includes CLI support and extensible structure for connecting AI systems (LLMs) to external data sources like ip-api.com. Ideal template for creating new MCP integrations via Node.js.

Installation

Run this command in your terminal to add the MCP server to Claude Code.

Run in terminal:

View docs

Command

claude mcp add --transport stdio aashari-boilerplate-mcp-server node dist/index.js \
  --env PORT="3000" \
  --env TRANSPORT_MODE="http"

How to use

This boilerplate MCP server provides a production-ready foundation for building and exposing your own MCP tools, resources, and prompts in TypeScript. It supports dual transports: STDIO for local AI assistant integrations (e.g., Claude Desktop, Cursor) and a Streamable HTTP transport for web-based or remote integrations. After building, you can run either transport mode to expose the MCP endpoints at the configured ports. Use the CLI and mcp scripts to test commands, validate tooling, and inspect responses. The project emphasizes security, type safety with Zod, and a layered architecture that cleanly separates concerns across CLI, tools, resources, prompts, controllers, services, and utilities.

How to install

Prerequisites:

Node.js >= 20.x
Git

Install and run locally:

Clone the repository git clone https://github.com/aashari/boilerplate-mcp-server.git cd boilerplate-mcp-server
Install dependencies npm install
Build the project (produces dist/) npm run build
Run in STDIO mode (for local AI assistants) TRANSPORT_MODE=stdio node dist/index.js
Run in HTTP mode (for web-based integrations) TRANSPORT_MODE=http PORT=3000 node dist/index.js
Optional: start a development server with MCP Inspector npm run mcp:inspect

Notes:

Use npm run cli to test individual MCP commands from the CLI helper.
The repository ships with scripts like mcp:stdio, mcp:http, and mcp:inspect for convenience.

Additional notes

Tips and common considerations:

The server binds to localhost by design; for production deployments consider enabling authentication per SECURITY.md guidance.
The Streamable HTTP transport supports multiple concurrent connections and uses Server-Sent Events (SSE).
Environment variables can be tuned via the mcp config entries (e.g., PORT, TRANSPORT_MODE). Ensure those are set consistently across deployment environments.
When debugging, use npm run mcp:inspect to launch a UI that helps inspect MCP messages, tools, and resources.
If you upgrade MCP SDK versions, check docs/MODERNIZATION.md for any updated registerTool usage and transport changes.

Related MCP Servers

mcp-telegram

233

MCP Server for Telegram

Remote

206

A type-safe solution to remote MCP communication, enabling effortless integration for centralized management of Model Context.

brainstorm

MCP server for multi-round AI brainstorming debates between multiple models (GPT, DeepSeek, Groq, Ollama, etc.)

unity

A Unity MCP server that allows MCP clients like Claude Desktop or Cursor to perform Unity Editor actions.

protocols-io

An MCP server that enables MCP clients like Claude Desktop to interact with data from protocols.io.

vscode-context

MCP Server to Connect with VS Code IDE