🚀 MCP Template

A Model Context Protocol (MCP) server template for Node.js with TypeScript support.

📋 Overview

This is a comprehensive MCP server template that provides a robust foundation for building Model Context Protocol servers. It supports multiple transport modes: stdio, SSE (Server-Sent Events), and HTTP streams, making it suitable for various integration scenarios. The template includes authentication, logging, and a sample weather tool to demonstrate the MCP tool implementation pattern.

� Prerequisites

Node.js 18+
npm or pnpm
TypeScript knowledge for customization

�🛠️ Installation

# Clone the repository
git clone https://github.com/pshaddel/mcp-template.git
cd mcp-template

# Install dependencies
npm install
# or
pnpm install

# Build the project
npm run build

⚙️ Configuration

Create a .env file based on the sample provided:

cp .sample.env .env

Configure the following environment variables:

Variable	Description	Default	Required
`MODE`	Transport mode: `stdio`, `sse`, or `http-streams`	`stdio`	Yes
`API_KEYS`	Comma-separated list of allowed API keys (SSE/HTTP streams mode only)	-	No (required for SSE/HTTP streams)
`APP_PORT`	Port for SSE/HTTP streams server	`3000`	No

Example Configuration

For stdio mode (Claude Desktop):

MODE=stdio

For SSE mode (HTTP server):

MODE=sse
API_KEYS=your_api_key1,your_api_key2
APP_PORT=3000

For HTTP streams mode (HTTP server with streaming):

MODE=http-streams
API_KEYS=your_api_key1,your_api_key2
APP_PORT=3000

🏃‍♀️ Running the Service

Development Mode

npm run dev
# or
npm run start:dev
# or with pnpm
pnpm dev

Production Mode

npm start
# or with pnpm
pnpm start

MCP Inspector

The MCP Inspector is a powerful debugging tool that provides a web interface to test and interact with your MCP server tools during development.

How to run

npx @modelcontextprotocol/inspector

This will start the inspector and open it in your browser (typically at http://localhost:5173).

Configuration

The inspector supports different transport modes depending on how your MCP server is running:

SSE Configuration

When running your server in SSE mode:

URL: http://localhost:3000/sse (or your configured port)
Headers: Add the following header for authentication:
- Header Name: x-api-key
- Header Value: Your API key from the .env file

HTTP Streams Configuration

When running your server in HTTP streams mode:

URL: http://localhost:3000/mcp (or your configured port)
Headers: Add the following header for authentication:
- Header Name: x-api-key
- Header Value: Your API key from the .env file

Usage Tips

Start your MCP server first in either SSE or HTTP streams mode
The inspector will automatically detect available tools and display their schemas
You can test tools interactively and see real-time responses
Use the inspector to validate your tool implementations before integrating with other clients

�🔌 Integration

Claude Desktop Integration

Build the project:

npm run build

Add the following configuration to your Claude Desktop config file:

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json Windows: %APPDATA%\Claude\claude_desktop_config.json

{
    "mcpServers": {
        "mcp-template": {
            "command": "node",
            "args": [
                "--env-file=/path/to/your/project/.env",
                "/path/to/your/project/build/main.js"
            ]
        }
    }
}

3.Then restart Claude Desktop. and you should see the MCP server listed in the settings.

n8n Integration

Run the application in sse or http-streams mode. If running locally, use npm run dev or npm start.
- For SSE mode: server will be available at http://localhost:3000/sse
- For HTTP streams mode: server will be available at http://localhost:3000/mcp
If you are running n8n in a docker container, you cannot use http://localhost:3000 as the n8n container cannot access the host's localhost. Instead, you can use http://host.docker.internal:3000 to access the host's services from within the n8n container, or you can run the n8n container with the --network="host" option to share the host's network stack.
Run the n8n instance, if locally, use the following command:

docker run -it --rm \
    -p 5678:5678 \
    -v ~/.n8n:/home/node/.n8n \
    n8nio/n8n

Open n8n in your browser at http://localhost:5678.
Create a new workflow and add an AI Agent node.
In Tools section, add a MCP Client Tool node.
Configure the MCP Client Tool node with the following settings:
- Server URL:
  - For SSE mode: http://host.docker.internal:3000/sse
  - For HTTP streams mode: http://host.docker.internal:3000/mcp
- API Key: Add a custom header x-api-key with your API key from the .env file.

The Tools Should be available now.

HTTP Streams Integration

When running in HTTP streams mode, the server provides streamable HTTP endpoints for MCP communication with session management:

Base URL: http://localhost:3000 (or your configured port)

Endpoints:

POST /mcp - Initialize session or send MCP messages
GET /mcp - Retrieve server-to-client notifications (requires session ID)
DELETE /mcp - Terminate MCP session
GET /health - Health check endpoint

Session Management: HTTP streams mode uses session-based communication. Include the mcp-session-id header in requests after initialization:

# Initialize a new session
curl -X POST \
  -H "x-api-key: your_api_key" \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2024-11-05","capabilities":{},"clientInfo":{"name":"test-client","version":"1.0.0"}}}' \
  http://localhost:3000/mcp

# Use the returned session ID in subsequent requests
curl -X POST \
  -H "x-api-key: your_api_key" \
  -H "mcp-session-id: your-session-id" \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":2,"method":"tools/list"}' \
  http://localhost:3000/mcp

Authentication: Set the x-api-key header with one of your configured API keys for all requests.

VS Code Integration

Enable MCP support in VS Code in settings.

Use it via VS Code by adding the following to your .vscode/mcp.json file:

{
    "servers": {
        "mcp-template": {
            "type": "stdio",
            "command": "node",
            "args": [
                "--env-file=/path/to/your/project/.env",
                "/path/to/your/project/build/main.js"
            ]
        }
    },
    "inputs": []
}

Start using it in VS Code by running the MCP commands in Copilot Chat(In Agent mode).

SSE Server Integration

When running in SSE mode, the server provides HTTP endpoints for MCP communication:

Base URL: http://localhost:3000 (or your configured port)

Endpoints:

GET /sse - Establish SSE connection
POST /messages - Send MCP messages
GET /health - Health check endpoint

Authentication: Set the x-api-key header with one of your configured API keys:

curl -H "x-api-key: your_api_key" http://localhost:3000/sse

🧰 Available Tools

1. `weather`

Fetches weather data from the Open Meteo API.

Input Parameters:

Parameter	Type	Description	Example
`latitude`	string	Latitude of the location	`"47.8095"`
`longitude`	string	Longitude of the location	`"13.0550"`
`start_date`	string	Start date (YYYY-MM-DD)	`"2025-07-25"`
`end_date`	string	End date (YYYY-MM-DD)	`"2025-07-25"`
`timezone`	enum	Timezone	`"Europe/London"`

Supported Timezones:

Europe/London
America/New_York
Asia/Tokyo

Example Usage:

{
  "latitude": "47.8095",
  "longitude": "13.0550",
  "start_date": "2025-07-25",
  "end_date": "2025-07-25",
  "timezone": "Europe/London"
}

🛠️ Development

Project Structure

src/
├── main.ts              # Main server entry point
├── tools/               # MCP tools directory
│   ├── tool.interface.ts # Tool interface definition
│   └── weather.ts       # Weather tool implementation
└── tests/               # Test files
    └── weather.test.ts  # Weather tool tests

Adding New Tools

Create a new tool file in src/tools/:

import { z } from 'zod';
import { Tool } from './tool.interface.js';

export const myTool: Tool = {
    tool_name: 'my_tool',
    description: 'Description of what your tool does',
    inputSchema: {
        // Define your input schema using zod validators
        param1: z.string().describe('Parameter description'),
    },
    function: async (args) => {
        // Implement your tool logic here
        return {
            content: [{
                type: 'text',
                text: 'Tool response'
            }]
        };
    }
};

Register the tool in src/main.ts:

import { myTool } from './tools/my-tool.js';

// Add this line after the existing tool registration
mcpServer.registerTool(myTool.tool_name, {
    description: myTool.description,
    inputSchema: myTool.inputSchema,
}, myTool.function);

Available Scripts

Script	Description
`npm run build`	Compile TypeScript to JavaScript
`npm run dev`	Run in development mode with hot reload
`npm run start:dev`	Alternative development command
`npm start`	Run the built server
`npm run test:coverage`	Run tests with coverage report

🐳 Docker Support

Build and run with Docker:

# Build the Docker image
docker build -t mcp-template .

# Run the container
docker run -p 3000:3000 --env-file .env mcp-template

� Testing

Run tests to ensure everything works correctly:

npm test              # Run tests
npm run test:coverage # Run tests with coverage
# or
pnpm test
pnpm run test:coverage

🔧 Troubleshooting

Common Issues

"Transport not found" error in SSE/HTTP streams mode:

Ensure the SSE connection is established before sending messages (SSE mode)
Check that the sessionId is properly passed in requests (HTTP streams mode)
Verify the correct endpoint is being used (/sse for SSE, /mcp for HTTP streams)

Session management issues (HTTP streams mode):

Ensure you initialize a session with the initialize method before other requests
Include the mcp-session-id header in all requests after initialization
Check that the session hasn't expired or been terminated

Permission errors:

Verify the API key is correctly set in headers
Check that the API key exists in your API_KEYS environment variable

Build errors:

Run npm run build to ensure TypeScript compilation succeeds
Check that all dependencies are installed

Debug Mode

Enable detailed logging by setting the log level:

// In main.ts, modify the capabilities
capabilities: {
    logging: {
        level: 'debug', // Change from 'info' to 'debug'
        format: 'json',
        destination: 'stdout',
    }
}

📚 Resources

�🤝 Contributing

Contributions are welcome! Please follow these steps:

Fork the repository
Create a feature branch (git checkout -b feature/amazing-feature)
Make your changes
Add tests for new functionality
Commit your changes (git commit -m 'Add amazing feature')
Push to the branch (git push origin feature/amazing-feature)
Open a Pull Request

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

🙏 Acknowledgments

Anthropic for the Model Context Protocol
Open Meteo for the weather API used in the example tool

Name		Name	Last commit message	Last commit date
Latest commit History 40 Commits
.github/workflows		.github/workflows
.vscode		.vscode
src		src
.c8rc.json		.c8rc.json
.dockerignore		.dockerignore
.gitignore		.gitignore
Dockerfile		Dockerfile
README.md		README.md
biome.json		biome.json
claude_desktop_config.json		claude_desktop_config.json
codecov.yml		codecov.yml
package.json		package.json
pnpm-lock.yaml		pnpm-lock.yaml
tsconfig.json		tsconfig.json

pshaddel/mcp-template

Folders and files

Latest commit

History

Repository files navigation

🚀 MCP Template

📋 Overview

� Prerequisites

�🛠️ Installation

⚙️ Configuration

Example Configuration

🏃‍♀️ Running the Service

Development Mode

Production Mode

MCP Inspector

How to run

Configuration

SSE Configuration

HTTP Streams Configuration

Usage Tips

�🔌 Integration

Claude Desktop Integration

n8n Integration

HTTP Streams Integration

VS Code Integration

SSE Server Integration

🧰 Available Tools

1. weather

🛠️ Development

Project Structure

Adding New Tools

Available Scripts

🐳 Docker Support

� Testing

🔧 Troubleshooting

Common Issues

Common Issues

Debug Mode

📚 Resources

�🤝 Contributing

📄 License

🙏 Acknowledgments

About

Topics

Resources

Uh oh!

Stars

Watchers

Forks

Releases

Contributors 2

Uh oh!

Languages

1. `weather`