MCP Server Template

A comprehensive template for building Model Context Protocol (MCP) servers with TypeScript.

Features

• ✅ TypeScript - Full type safety and modern JavaScript features
• ✅ Example Implementations - Tools, resources, and prompts examples
• ✅ Comprehensive Documentation - Detailed CLAUDE.md for Claude Code
• ✅ Testing Setup - Vitest configuration and example tests
• ✅ ESLint Configuration - Code quality and consistency
• ✅ Production Ready - Built-in error handling and logging

Quick Start

# 1. Use this template
Click "Use this template" button on GitHub

# 2. Clone your new repository
git clone https://github.com/yourusername/your-mcp-server.git
cd your-mcp-server

# 3. Install dependencies
npm install

# 4. Build the project
npm run build

# 5. Test with MCP Inspector
npx @modelcontextprotocol/inspector dist/index.js

What's Included

Example Implementations

This template includes working examples of:

1. Tools - Functions Claude can call

   • example_tool - Processes and transforms text

2. Resources - Data Claude can access

   • example://resource - JSON data resource

3. Prompts - Reusable prompt templates

   • example_prompt - Topic-based prompt generation

Project Structure

mcp-server-template/
├── src/
│   ├── index.ts              # Main server entry point
│   ├── tools/                # Tool implementations
│   │   └── example.ts
│   ├── resources/            # Resource implementations
│   │   └── example.ts
│   └── prompts/              # Prompt implementations
│       └── example.ts
├── dist/                     # Compiled output (generated)
├── package.json
├── tsconfig.json
├── CLAUDE.md                 # Comprehensive Claude Code documentation
└── README.md                 # This file

Installation

As a Local Development Server

npm run build
claude mcp add my-server node /absolute/path/to/dist/index.js

After Publishing to npm

npm publish
claude mcp add my-server npx -y your-package-name

Development

npm install          # Install dependencies
npm run build        # Build TypeScript
npm run dev          # Watch mode for development
npm test             # Run tests
npm run lint         # Lint code
npm run lint:fix     # Fix linting issues

Usage with Claude Code

After installation, your MCP server will be available in Claude Code:

# Claude can now use your tools
User: "Use the example_tool to process 'hello world'"

# Claude can access your resources
User: "Read the example resource"

# Claude can use your prompts
User: "Use the example_prompt for 'MCP servers'"

Customization

1. Update Package Metadata

Edit package.json:

{
  "name": "your-mcp-server",
  "version": "1.0.0",
  "description": "Your server description",
  "author": "Your Name"
}

2. Add Your Tools

Create new tool files in src/tools/:

// src/tools/myTool.ts
export async function myTool(args: { input: string }) {
  // Your implementation
  return {
    content: [
      {
        type: "text",
        text: `Result: ${args.input}`,
      },
    ],
  };
}

Register in src/index.ts:

import { myTool } from "./tools/myTool.js";

// Add to tools list and call handler

3. Add Your Resources

Create resource files in src/resources/ following the same pattern.

4. Add Your Prompts

Create prompt files in src/prompts/ following the same pattern.

Documentation

All documentation for working with Claude Code is in CLAUDE.md:

• Core Concepts (Tools, Resources, Prompts)
• Development Guide with step-by-step instructions
• Testing strategies
• Deployment procedures
• Troubleshooting guide
• Best practices

Use Cases

This template is perfect for building:

• 🔧 API Integrations - Connect Claude to external APIs
• 📁 File System Tools - Custom file operations
• 🗄️ Database Access - Query and manage databases
• 🌐 Web Scrapers - Fetch and process web content
• 📊 Data Processors - Transform and analyze data
• 🤖 Automation Tools - Automate workflows

Testing

Local Testing with MCP Inspector

npm run build
npx @modelcontextprotocol/inspector dist/index.js

The inspector provides an interactive UI for testing tools, resources, and prompts.

Unit Testing

npm test                    # Run all tests
npm test -- --watch        # Watch mode
npm test -- --coverage     # Coverage report

Technologies

• TypeScript 5.3.3
• MCP SDK 1.0.4
• Vitest 1.1.0 (testing)
• ESLint 8.56.0 (linting)

Resources

• MCP Specification
• MCP SDK Documentation
• Claude Code Documentation
• Example MCP Servers

License

MIT

Contributing

1. Fork the repository
2. Create your feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

Template Info

Version: 1.0.0 Last Updated: 2025 Template Purpose: Building Model Context Protocol (MCP) servers

---

⭐ Star this template if you find it useful!

📝 Check CLAUDE.md for comprehensive documentation when working with Claude Code