Starter Template

TypeScript MCP License: MIT

Build production-ready MCP servers in minutes. Works with Claude Desktop, Cursor, Windsurf, and any MCP-compatible client.

What is MCP?

Model Context Protocol (MCP) by Anthropic lets AI assistants securely connect to external tools, databases, and APIs. This template gives you a working MCP server you can customize for your needs.

Features

• ✅ TypeScript — Full type safety with the official MCP SDK
• ✅ Tools — Define custom tools that AI can call
• ✅ Resources — Expose data that AI can read
• ✅ Prompts — Reusable prompt templates
• ✅ Error Handling — Structured error responses
• ✅ Logging — Built-in stderr logging (MCP-compliant)
• ✅ Hot Reload — Development with tsx watch
• ✅ Tests — Vitest setup included
• ✅ CI/CD — GitHub Actions workflow

Quick Start

# Clone this template
git clone https://github.com/spinov001-art/mcp-server-starter-template.git
cd mcp-server-starter-template

# Install dependencies
npm install

# Run in development
npm run dev

# Build for production
npm run build
npm start

Project Structure

src/
├── index.ts          # Server entry point
├── tools/
│   └── example.ts    # Example tool implementation
├── resources/
│   └── example.ts    # Example resource provider
└── prompts/
    └── example.ts    # Example prompt template

Adding Your First Tool

// src/tools/weather.ts
import { z } from "zod";

export const weatherTool = {
  name: "get_weather",
  description: "Get current weather for a city",
  inputSchema: z.object({
    city: z.string().describe("City name"),
  }),
  handler: async ({ city }: { city: string }) => {
    const response = await fetch(
      `https://wttr.in/${encodeURIComponent(city)}?format=j1`
    );
    const data = await response.json();
    return {
      content: [
        {
          type: "text" as const,
          text: JSON.stringify(data.current_condition[0], null, 2),
        },
      ],
    };
  },
};

Adding a Resource

// src/resources/config.ts
export const configResource = {
  uri: "config://app",
  name: "App Configuration",
  description: "Current application configuration",
  mimeType: "application/json",
  handler: async () => ({
    contents: [
      {
        uri: "config://app",
        mimeType: "application/json",
        text: JSON.stringify({
          version: "1.0.0",
          environment: process.env.NODE_ENV || "development",
        }),
      },
    ],
  }),
};

Connect to Claude Desktop

Add to your Claude Desktop config (~/Library/Application Support/Claude/claude_desktop_config.json):

{
  "mcpServers": {
    "my-server": {
      "command": "node",
      "args": ["/path/to/mcp-server-starter-template/dist/index.js"]
    }
  }
}

Connect to Cursor / Windsurf

Add to .cursor/mcp.json or equivalent:

{
  "mcpServers": {
    "my-server": {
      "command": "node",
      "args": ["./dist/index.js"]
    }
  }
}

Entry Point Template

// src/index.ts
import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";

const server = new McpServer({
  name: "my-mcp-server",
  version: "1.0.0",
});

// Register a tool
server.tool("hello", "Say hello to someone", {
  name: { type: "string", description: "Name to greet" },
}, async ({ name }) => ({
  content: [{ type: "text", text: `Hello, ${name}! 👋` }],
}));

// Start server
const transport = new StdioServerTransport();
await server.connect(transport);
console.error("MCP server running on stdio");

package.json

{
  "name": "mcp-server-starter-template",
  "version": "1.0.0",
  "type": "module",
  "scripts": {
    "build": "tsc",
    "start": "node dist/index.js",
    "dev": "tsx watch src/index.ts",
    "test": "vitest"
  },
  "dependencies": {
    "@modelcontextprotocol/sdk": "^1.0.0",
    "zod": "^3.22.0"
  },
  "devDependencies": {
    "tsx": "^4.7.0",
    "typescript": "^5.3.0",
    "vitest": "^1.2.0"
  }
}

Real-World MCP Server Ideas

Server	Description	Difficulty
Database Explorer	Query SQLite/PostgreSQL from AI	⭐⭐
File Manager	Read/write/search local files	⭐
API Gateway	Connect any REST API to AI	⭐⭐
Web Scraper	Extract data from websites	⭐⭐⭐
Email Client	Read/send emails via AI	⭐⭐
Calendar	Manage Google Calendar events	⭐⭐
Slack Bot	Send/read Slack messages	⭐⭐
Git Helper	Advanced git operations	⭐⭐
Docker Manager	Container lifecycle management	⭐⭐⭐
Analytics	Query Mixpanel/Amplitude data	⭐⭐⭐

Resources

• MCP Specification
• MCP TypeScript SDK
• MCP Python SDK
• Awesome MCP Tools 2026 — 130+ MCP servers & tools
• Awesome Web Scraping 2026 — 150+ scraping tools

Contributing

PRs welcome! Please read CONTRIBUTING.md before submitting.

License

MIT — use this template for anything.

---

Built by spinov001-art | Hire me for web scraping & data extraction