mcp-server

A starter Model Context Protocol (MCP) server, built with the official TypeScript SDK.

It ships with two example tools:

• echo — echoes a message back to the caller (useful for testing connectivity)

• get_time — returns the current date/time, optionally in a given IANA timezone

Use these as templates, then add your own tools in src/index.ts.

Getting started

npm install
npm run build
npm start

The server communicates over stdio, so it's meant to be launched by an MCP client (e.g. Claude Desktop, Claude Code) rather than run standalone.

Related MCP server: TypeScript MCP Server Boilerplate

Development

npm run dev   # watch mode, recompiles on change

Test interactively with the MCP Inspector:

npm run build
npm run inspector

Connecting to an MCP client

Add an entry pointing at the built server, e.g. for Claude Desktop's claude_desktop_config.json:

{
  "mcpServers": {
    "mcp-server": {
      "command": "node",
      "args": ["/absolute/path/to/mcp-server/build/index.js"]
    }
  }
}

Registering with the Claude Code CLI

You can also register this server (or any third-party MCP server) with the claude mcp add command instead of editing a client's config file by hand:

# This project, at user scope (available in every project on your machine)
claude mcp add mcp-server -s user -- node /absolute/path/to/mcp-server/build/index.js

The same pattern works for other MCP servers distributed via npm. A couple of examples:

Perplexity's MCP server (requires an API key):

claude mcp add perplexity -s user --env PERPLEXITY_API_KEY="your-api-key" -- npx -y @perplexity-ai/mcp-server

Playwright's MCP server (browser automation, no API key needed):

claude mcp add playwright -s user -- npx -y @playwright/mcp@latest

• -s user registers the server at user scope (all projects); use -s project to scope it to the current repo instead.

• --env KEY=value passes environment variables (e.g. API keys) to the server process.

• Everything after -- is the command used to launch the server.

• Replace "your-api-key" with a real key from the provider's dashboard — a placeholder value will cause auth failures.

Project structure

src/
  index.ts     # server entry point: tool definitions + handlers
build/         # compiled output (generated, gitignored)

Adding a new tool

1. Add its JSON schema to the TOOLS array in src/index.ts.

2. Handle it in the CallToolRequestSchema switch statement.

3. Validate its arguments with a zod schema, as the examples do.

4. Rebuild (npm run build) and reconnect your MCP client.