boilerplate-mcp-server MCP Server

Overview

boilerplate-mcp-server is an open-source TypeScript implementation designed to serve as a base for building Model Context Protocol servers. Maintained by user aashari, it provides developer infrastructure to connect artificial intelligence assistants to external APIs and data repositories. The codebase implements all core MCP primitives including tools, resources, and prompts, alongside an included IP geolocation sample implementation.

The project includes structured architectural layers, automated testing, and development tooling such as ESLint, Prettier, semantic-release, and MCP Inspector integration. Updated to MCP SDK 1.26.0 and Zod 4.3.6, the repository provides modern tool registration patterns, fallback mechanisms, and token-optimization features to manage data payload sizes when serving context to artificial intelligence models.

What it can do

The README lists these tools and features:

• Security First: DNS rebinding protection, localhost-only binding, secure error handling
• Dual Transport Support: STDIO and Streamable HTTP transports with automatic fallback
• Layered Architecture: Clean separation between CLI, tools, resources, prompts, controllers, services, and utilities
• Type Safety: Full TypeScript implementation with Zod v4.3.6 schema validation
• All MCP Primitives: Tools, resources, and prompts (with examples)
• ResourceLink Pattern: Token-efficient resource references for large responses
• TOON Output Format: Token-Oriented Object Notation for 30-60% fewer tokens than JSON
• JMESPath Filtering: Extract only needed fields from responses to reduce token costs
• Raw Response Logging: Automatic logging of large API responses to /tmp/mcp// with truncation guidance
• Modern SDK: Uses MCP SDK v1.26.0 with registerTool API pattern (ready for v2 migration)
• Complete IP Address Example: Tools, resources, prompts, and CLI commands for IP geolocation
• Comprehensive Testing: Unit and integration tests with coverage reporting (47 tests passing)
• Production Tooling: ESLint, Prettier, semantic-release, and MCP Inspector integration
• Error Handling: Structured error handling with isError field and contextual logging
• Security Documentation: Complete SECURITY.md with authentication implementation guides
• Purpose: MCP tool definitions that AI assistants can invoke
• Implementation: Zod schema validation with structured responses
• Example: ip_get_details tool with optional IP address and configuration options
• Pattern: Define schema → Validate args → Call controller → Format MCP response
• MCP Inspector: Visual tool for testing your MCP tools
• Run server with npm run mcp:inspect
• Open the URL shown in terminal
• Test your tools interactively
• Debug Logging: Enable with DEBUG=true environment variable
• Raw Response Logging: Large API responses (>40,000 characters) are automatically logged

The server relies on a layered architecture that separates command-line interfaces, tools, resources, prompts, controllers, services, and utilities. Requests received from host applications pass to controllers that handle core business logic and response formatting before retrieving data through service interfaces. The codebase uses Zod v4.3.6 to perform schema validation across these boundaries.

Communication operates through two main transport modes: STDIO and Streamable HTTP. STDIO mode exchanges JSON-RPC messages via standard input and output streams for local integrations like desktop clients. Streamable HTTP mode uses HTTP with Server-Sent Events to handle multiple concurrent connections. The HTTP server binds exclusively to localhost by default, serving MCP endpoints and a version health-check endpoint.

To handle context data efficiently, the server offers formatting and filtering options. In addition to standard JSON output, it supports Token-Oriented Object Notation, which formats structured data to consume fewer tokens. Users and clients can also supply JMESPath expressions to extract precise data fields, while large raw responses are logged locally for reference.

Install and configure

These commands were found in the project's own README. We checked each package name against the public registry.

npm install

(not a registry package: check the source before running it)

Environment variables:

Requirements

The package declares Node.js >=20.0.0 in its engines field. The README mentions setup for these clients: Claude Desktop, Cursor, Zed, Continue.

Use cases

Developers building custom MCP implementations can use this codebase as a starter template rather than constructing a protocol server from scratch. Its layered directory structure allows software engineers to substitute the included sample services with custom third-party API integrations, data source connectors, or internal system handlers.

The repository also suits applications needing optimized token consumption when delivering large contextual payloads to language models. By selecting alternative output encodings like Token-Oriented Object Notation or applying JMESPath extraction filters, integrations can trim redundant fields from responses before transmitting data to an connected assistant.

This project is designed for TypeScript software engineers, artificial intelligence developers, and system integrators who need a structured template for constructing custom Model Context Protocol servers. It benefits teams looking for preconfigured development workflows, testing setups, and token-reduction utilities.

Limitations and things to check

The repository requires a Node.js runtime version of at least 20.x along with Git for setup. While built-in protections include DNS rebinding validation, explicit localhost binding, and sanitized error outputs, network-facing deployments require additional authentication mechanisms like mTLS, OAuth 2.0, or bearer tokens that must be set up separately by the integrator.

The codebase does not list an open-source license in its primary repository information. Users should verify licensing terms before adopting it in commercial environments. Furthermore, raw response logging writes data to local temporary directories, which users should monitor depending on their host operating system storage policies.

Before you connect it:

• The README mentions: can run commands or code on your machine; needs credentials or api keys; controls or scrapes a web browser.
• Read the code or the documentation of the tools it exposes, and note what each tool can do.
• Grant the smallest permissions you can: limit folders, API scopes and database roles.
• Keep credentials in environment variables or a secrets manager, never in a shared config file.
• Run it in a container or a separate user account if it can execute code or touch files.

Release history

The most recent releases published on GitHub:

• v3.2.0 (2026-02-17): # 3.2.0 (2026-02-17) ### Features harden HTTP transport security and add tool annotations (5919f9f)
• v3.1.0 (2026-02-17): # 3.1.0 (2026-02-17) ### Features modernize HTTP transport and standardize MCP tool contracts (615b373)
• v3.0.0 (2026-02-04): # 3.0.0 (2026-02-04) ### Features migrate to OIDC trusted publishing for npm (long-term solution) (b7c36e3) ### BREAKING CHANGES Requires one-time OIDC configuration on npmjs.com See docs/OIDC-TRUSTED-PUBLISHING-SETUP.md for complete migration guide

Known issues and troubleshooting

These are the most discussed threads on the project's issue tracker. They show what other users ran into; read them before you install, and check whether they are still open.

• Test Gemini autonomous engineer (closed, 5 comments)

Maintenance and community

The repository has 5 contributors, 28 commits in the last 12 months, 14 open issues and pull requests. It is maintained by Andi Ashari, a GitHub user with 31 public repositories and 119 followers. GitHub's community checks found a security policy, no contribution guidelines, no code of conduct.

Frequently asked questions

Is boilerplate-mcp-server free to use?

GitHub lists no license for this repository. Without a license you have no clear right to use or copy the code, so ask the author before relying on it.

When was boilerplate-mcp-server last updated?

The last commit was on 2026-03-06, and the project is marked active by our 12-month check.

Which AI clients does boilerplate-mcp-server work with?

Its README gives setup notes for Claude Desktop, Cursor, Zed, Continue. Other MCP-compatible clients may also work, but the project does not say so.

What transport modes does the boilerplate support?

It supports standard input and output (STDIO) transport for local desktop integrations, as well as Streamable HTTP transport using Server-Sent Events for multi-connection web setups.

Which prerequisites are necessary to run the project?

The project requires Node.js version 20.x or higher, along with Git for version control.

How does the server optimize token usage for language models?

It uses Token-Oriented Object Notation (TOON) to format structured data using fewer tokens than JSON. It also supports JMESPath filtering to extract specific response fields.

Does the server require network authentication by default?

No. Local development binds strictly to localhost without authentication. Deployments exposed over a network require setting up authentication mechanisms like mTLS or OAuth 2.0.

Sources

This page combines data from:

• boilerplate-mcp-server on GitHub
• Architecture overview - Model Context Protocol
• TypeScript: The starting point for learning TypeScript