MCP Server Template

A starter template for building MCP (Model Context Protocol) servers in TypeScript

What You Get

A working MCP server with an example hello tool
TypeScript with ES modules
Testing with Vitest
Linting (ESLint) and formatting (Prettier)
CI pipeline and npm publishing workflow
VS Code, Claude Desktop, and Cursor configuration examples

┌─────────────────┐     ┌────────────┐     ┌──────────────────┐
│  AI Assistant    │────▶│ MCP Client │────▶│ Your MCP Server  │
│ (Copilot/Claude) │◀────│            │◀────│                  │
└─────────────────┘     └────────────┘     └──────────────────┘

Quick Start

1. Create your project

npx -y degit matracey/mcp-server-template my-mcp-server
cd my-mcp-server
npm install

2. Customize

Update name, description, and bin in package.json
Replace the example hello tool in src/server.ts with your own tools
Update the server name/version in src/server.ts

3. Build and test

npm run build
npm test

4. Run locally

npm run dev    # Run with auto-restart on file changes
npm start      # Run the built version

Adding Tools

Edit src/server.ts and register a new tool:

server.tool(
  'my_tool',
  'Description of what this tool does.',
  {
    param: z.string().describe('Parameter description'),
  },
  async ({ param }) => {
    return {
      content: [{ type: 'text' as const, text: `Result: ${param}` }],
    }
  }
)

The template includes an example hello tool to demonstrate the pattern.

Client Configuration

Once published (or running locally), configure your AI client:

VS Code (GitHub Copilot)

Add to .vscode/mcp.json:

{
  "servers": {
    "my-server": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "my-mcp-server"]
    }
  }
}

Claude Desktop

Add to claude_desktop_config.json:

{
  "mcpServers": {
    "my-server": {
      "command": "npx",
      "args": ["-y", "my-mcp-server"]
    }
  }
}

Cursor

Add to .cursor/mcp.json:

{
  "mcpServers": {
    "my-server": {
      "command": "npx",
      "args": ["-y", "my-mcp-server"]
    }
  }
}

Replace my-mcp-server with your published package name.

Project Structure

src/
├── index.ts          # Entry point — stdio transport setup
├── server.ts         # MCP server & tool definitions
├── __tests__/        # Tests (vitest)
└── data/             # Static data (if needed)
scripts/              # Dev-time scripts

Development

Prerequisites

Node.js >= 20
npm

Commands

npm run build           # TypeScript compilation
npm test                # Run tests
npm run test:watch      # Watch mode
npm run test:coverage   # With coverage report
npm run dev             # Run with auto-restart on changes
npm run validate        # Run all CI checks (format, lint, build, test)

Contributing

Contributions are welcome! Please see CONTRIBUTING.md for guidelines.

License

MIT — see LICENSE for details.

my-mcp-server