MCP Server Boilerplate
A TypeScript template for building Model Context Protocol servers with example tools, type-safe validation, and best practices for integrating custom functionality with AI assistants like Cursor and Claude.
README
MCP Server Boilerplate
A TypeScript template for building Model Context Protocol (MCP) servers.
This boilerplate provides a solid foundation for creating MCP servers that can integrate with Cursor, Claude, and other AI assistants. It includes best practices, example tools, proper error handling, and a well-structured TypeScript codebase.
What This Template Provides
- Complete MCP Server Setup: Ready-to-use server with proper configuration
- Example Tools: Demonstrates common MCP tool patterns and best practices
- TypeScript Integration: Full type safety with Zod validation
- Error Handling: Robust error handling patterns throughout
- Testing Setup: Vitest configuration for unit testing
- Development Workflow: Build, watch, and inspection scripts
Key Features
Type-Safe Development: Built with TypeScript and Zod for runtime validation and compile-time safety.
Modular Architecture: Well-organized code structure with separate modules for tools, utilities, and types.
Example Patterns: Demonstrates data retrieval, search, analytics, and system utilities.
Development Ready: Includes hot reload, testing, and MCP inspector integration.
Quick Start
1. Clone and Setup
git clone https://github.com/vltansky/mcp-boilerplate.git
cd mcp-server-boilerplate
yarn install
yarn build
2. Configure MCP Client
Add to your .cursor/mcp.json or other MCP client configuration:
{
"mcpServers": {
"my-custom-server": {
"command": "node",
"args": ["path/to/your/dist/server.js"]
}
}
}
3. Start Developing
yarn watch # Start development with hot reload
4. Test Your Tools
Use the MCP inspector to test your tools:
yarn inspector
Task Master - Getting Started
Once you have your MCP server running, here's how to get the most out of the Task Master workflow:
Next Steps for Project Success
-
Configure AI models (if needed) and add API keys to
.env- Models: Use
task-master modelscommands - Keys: Add provider API keys to .env (or inside the MCP config file i.e. .cursor/mcp.json)
- Models: Use
-
Discuss your idea with AI and ask for a PRD using example_prd.txt, and save it to scripts/PRD.txt
-
Ask Cursor Agent (or run CLI) to parse your PRD and generate initial tasks:
- MCP Tool: parse_prd | CLI: task-master parse-prd scripts/prd.txt
-
Ask Cursor to analyze the complexity of the tasks in your PRD using research
- MCP Tool: analyze_project_complexity | CLI: task-master analyze-complexity
-
Ask Cursor to expand all of your tasks using the complexity analysis
-
Ask Cursor to begin working on the next task
-
Add new tasks anytime using the add-task command or MCP tool
-
Ask Cursor to set the status of one or many tasks/subtasks at a time. Use the task id from the task lists.
-
Ask Cursor to update all tasks from a specific task id based on new learnings or pivots in your project.
-
Ship it!
Example Tools Included
Core Tools
get_data- Demonstrates data retrieval with filtering and paginationsearch_items- Shows search functionality with multiple search types (exact, fuzzy, regex)analyze_data- Example analytics tool with chart data generationget_system_info- System utilities for date, timezone, and version information
Tool Patterns Demonstrated
- Parameter Validation: Using Zod schemas for type-safe input validation
- Error Handling: Consistent error handling and user-friendly error messages
- Async Operations: Proper async/await patterns with timeout simulation
- Response Formatting: JSON and compact-JSON output modes
- Type Safety: Full TypeScript integration with proper type inference
Project Structure
src/
├── server.ts # Main MCP server setup and tool registration
├── tools/
│ └── example-tools.ts # Example tool implementations
└── utils/
└── formatter.ts # Response formatting utilities
docs/ # Documentation files
package.json # Dependencies and scripts
tsconfig.json # TypeScript configuration
vitest.config.ts # Testing configuration
Customizing for Your Use Case
1. Replace Example Tools
Edit src/tools/example-tools.ts to implement your business logic:
export async function yourCustomOperation(input: YourInputType): Promise<YourOutputType> {
// Your implementation here
return result;
}
2. Update Server Registration
Modify src/server.ts to register your tools:
server.tool(
'your_tool_name',
'Description of what your tool does',
{
// Zod schema for parameters
param1: z.string().describe('Parameter description'),
param2: z.number().optional().default(10)
},
async (input) => {
// Tool implementation
const result = await yourCustomOperation(input);
return {
content: [{
type: 'text',
text: formatResponse(result, input.outputMode)
}]
};
}
);
3. Add Your Data Layer
Create modules for your specific data sources:
src/
├── database/ # Database connections and queries
├── external-apis/ # External API integrations
├── file-system/ # File system operations
└── your-domain/ # Your business logic
Development Workflow
Available Scripts
yarn build- Compile TypeScript to JavaScriptyarn watch- Watch mode for developmentyarn start- Run the compiled serveryarn test- Run unit testsyarn test:ui- Run tests with UIyarn inspector- Start MCP inspector for testing tools
Testing Your Tools
- Unit Tests: Add tests alongside your tool files
- Integration Testing: Use the MCP inspector to test tool behavior
- Manual Testing: Test with actual MCP clients like Cursor
Adding Dependencies
For data sources, add appropriate dependencies:
# Database
yarn add sqlite3 @types/sqlite3
# HTTP requests
yarn add axios
# File processing
yarn add fs-extra @types/fs-extra
# Date handling
yarn add date-fns
MCP Best Practices
Tool Design
- Clear Descriptions: Write detailed tool descriptions for AI assistants
- Parameter Validation: Use Zod for runtime validation
- Error Handling: Provide meaningful error messages
- Output Consistency: Use consistent response formats
Performance
- Async Operations: Use async/await for all I/O operations
- Resource Management: Clean up resources properly
- Caching: Implement caching for expensive operations
- Pagination: Support pagination for large datasets
Security
- Input Validation: Validate all inputs with Zod
- Error Messages: Don't expose sensitive information in errors
- Resource Limits: Implement appropriate limits and timeouts
- Authentication: Add authentication if accessing sensitive data
Common Use Cases
File System Tools
- File search and indexing
- Content analysis
- Code parsing and analysis
Database Integration
- Query interfaces
- Data analysis and reporting
- Schema exploration
External API Integration
- API wrapping and simplification
- Data aggregation from multiple sources
- Rate limiting and caching
Development Tools
- Code generation
- Testing utilities
- Build and deployment helpers
Contributing
- Fork this repository
- Create your feature branch
- Add tests for new functionality
- Ensure all tests pass
- Submit a pull request
License
MIT License - feel free to use this template for your own projects.
Resources
Ready to build your MCP server? Start by customizing the example tools in src/tools/example-tools.ts and updating the server registration in src/server.ts.
Recommended Servers
playwright-mcp
A Model Context Protocol server that enables LLMs to interact with web pages through structured accessibility snapshots without requiring vision models or screenshots.
Magic Component Platform (MCP)
An AI-powered tool that generates modern UI components from natural language descriptions, integrating with popular IDEs to streamline UI development workflow.
Audiense Insights MCP Server
Enables interaction with Audiense Insights accounts via the Model Context Protocol, facilitating the extraction and analysis of marketing insights and audience data including demographics, behavior, and influencer engagement.
VeyraX MCP
Single MCP tool to connect all your favorite tools: Gmail, Calendar and 40 more.
Kagi MCP Server
An MCP server that integrates Kagi search capabilities with Claude AI, enabling Claude to perform real-time web searches when answering questions that require up-to-date information.
graphlit-mcp-server
The Model Context Protocol (MCP) Server enables integration between MCP clients and the Graphlit service. Ingest anything from Slack to Gmail to podcast feeds, in addition to web crawling, into a Graphlit project - and then retrieve relevant contents from the MCP client.
Qdrant Server
This repository is an example of how to create a MCP server for Qdrant, a vector search engine.
Neon Database
MCP server for interacting with Neon Management API and databases
Exa Search
A Model Context Protocol (MCP) server lets AI assistants like Claude use the Exa AI Search API for web searches. This setup allows AI models to get real-time web information in a safe and controlled way.
E2B
Using MCP to run code via e2b.