MCP Server Boilerplate

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.

Category
Visit Server

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

  1. Configure AI models (if needed) and add API keys to .env

    • Models: Use task-master models commands
    • Keys: Add provider API keys to .env (or inside the MCP config file i.e. .cursor/mcp.json)
  2. Discuss your idea with AI and ask for a PRD using example_prd.txt, and save it to scripts/PRD.txt

  3. 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
  4. Ask Cursor to analyze the complexity of the tasks in your PRD using research

    • MCP Tool: analyze_project_complexity | CLI: task-master analyze-complexity
  5. Ask Cursor to expand all of your tasks using the complexity analysis

  6. Ask Cursor to begin working on the next task

  7. Add new tasks anytime using the add-task command or MCP tool

  8. Ask Cursor to set the status of one or many tasks/subtasks at a time. Use the task id from the task lists.

  9. Ask Cursor to update all tasks from a specific task id based on new learnings or pivots in your project.

  10. Ship it!

Example Tools Included

Core Tools

  • get_data - Demonstrates data retrieval with filtering and pagination
  • search_items - Shows search functionality with multiple search types (exact, fuzzy, regex)
  • analyze_data - Example analytics tool with chart data generation
  • get_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 JavaScript
  • yarn watch - Watch mode for development
  • yarn start - Run the compiled server
  • yarn test - Run unit tests
  • yarn test:ui - Run tests with UI
  • yarn inspector - Start MCP inspector for testing tools

Testing Your Tools

  1. Unit Tests: Add tests alongside your tool files
  2. Integration Testing: Use the MCP inspector to test tool behavior
  3. 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

  1. Fork this repository
  2. Create your feature branch
  3. Add tests for new functionality
  4. Ensure all tests pass
  5. 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

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.

Official
Featured
TypeScript
Magic Component Platform (MCP)

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.

Official
Featured
Local
TypeScript
Audiense Insights MCP Server

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.

Official
Featured
Local
TypeScript
VeyraX MCP

VeyraX MCP

Single MCP tool to connect all your favorite tools: Gmail, Calendar and 40 more.

Official
Featured
Local
Kagi MCP Server

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.

Official
Featured
Python
graphlit-mcp-server

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.

Official
Featured
TypeScript
Qdrant Server

Qdrant Server

This repository is an example of how to create a MCP server for Qdrant, a vector search engine.

Official
Featured
Neon Database

Neon Database

MCP server for interacting with Neon Management API and databases

Official
Featured
Exa Search

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.

Official
Featured
E2B

E2B

Using MCP to run code via e2b.

Official
Featured