Skip to main content
Glama
Example MCP Server

Example MCP Server

by Ranjith63812

Example MCP Server

A complete Model Context Protocol (MCP) server implementation in Node.js + TypeScript that integrates with Claude Desktop as a local tool.

What is MCP?

The Model Context Protocol (MCP) is a standardized protocol that enables large language models (like Claude) to safely interact with external tools and data sources. MCP servers expose capabilities (tools) that Claude can discover and invoke in real-time during conversations.

Key Features of MCP:

  • Tool Discovery: Claude can query available tools and their parameters

  • Safe Execution: Structured JSON-RPC messages with validation

  • Stdio Transport: For local integration with Claude Desktop

  • Extensible: Easy to add new tools with standardized interfaces

Related MCP server: TypeScript MCP Server Boilerplate

Project Structure

example-mcp-server/
├── src/
│   ├── mcp/
│   │   └── server.ts          # MCP server with stdio transport
│   ├── tools/
│   │   ├── index.ts           # Tool registry & dispatcher
│   │   ├── ping.ts            # Ping tool (health check)
│   │   └── system_info.ts     # System info tool
│   └── types/
│       └── index.ts           # Type definitions
├── package.json               # Dependencies & scripts
├── tsconfig.json              # TypeScript config
├── mcp.json                   # Claude Desktop manifest
└── README.md                  # This file

Getting Started

Prerequisites

  • Node.js 18+ (LTS)

  • npm or yarn

  • Claude Desktop (for testing)

Installation

  1. Clone or navigate to the project directory:

cd example-mcp-server
  1. Install dependencies:

npm install
  1. Build the TypeScript code:

npm run build

This compiles all .ts files in src/ to JavaScript in the dist/ folder.

Running the MCP Server

npm start

The server will start listening on stdin/stdout, ready to receive JSON-RPC messages.

Testing the Server Locally

Using curl with echo (Windows PowerShell)

Test the tools/list endpoint:

$message = @{
    jsonrpc = "2.0"
    id = 1
    method = "tools/list"
} | ConvertTo-Json -Compress
"$message" | node dist/mcp/server.js

Using a Node.js test script

Create test.js:

import { spawn } from "child_process";

const server = spawn("node", ["dist/mcp/server.js"]);

let output = "";

server.stdout.on("data", (data) => {
  const line = data.toString().trim();
  if (line) {
    console.log("Response:", JSON.parse(line));
    server.kill();
  }
});

server.on("close", () => {
  console.log("Server closed");
});

// Send initialize request
const initMsg = {
  jsonrpc: "2.0",
  id: 1,
  method: "initialize",
  params: {
    protocolVersion: "2024-11-05",
    capabilities: {},
    clientInfo: { name: "test-client", version: "1.0.0" },
  },
};

server.stdin.write(JSON.stringify(initMsg) + "\n");

// Wait a moment, then send tools/list
setTimeout(() => {
  const listMsg = { jsonrpc: "2.0", id: 2, method: "tools/list" };
  server.stdin.write(JSON.stringify(listMsg) + "\n");
}, 100);

Run with:

npm run build && node test.js

Available Tools

1. ping

A simple health check tool.

Request:

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "ping",
    "arguments": {}
  }
}

Response:

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "output": "pong"
  }
}

2. system_info

Returns system and platform information.

Request:

{
  "jsonrpc": "2.0",
  "id": 2,
  "method": "tools/call",
  "params": {
    "name": "system_info",
    "arguments": {}
  }
}

Response:

{
  "jsonrpc": "2.0",
  "id": 2,
  "result": {
    "output": {
      "platform": "win32",
      "arch": "x64",
      "nodeVersion": "v20.10.0",
      "osType": "Windows_NT",
      "osRelease": "10.0.22621",
      "totalMemory": "16384 MB",
      "freeMemory": "8192 MB",
      "cpuCount": 8,
      "uptime": "24 hours"
    }
  }
}

Registering with Claude Desktop

To make this MCP server available in Claude Desktop:

Windows

  1. Open %APPDATA%\Claude\claude_desktop_config.json

  2. Add this server configuration:

{
  "mcpServers": {
    "example-mcp-server": {
      "command": "node",
      "args": ["C:\\path\\to\\example-mcp-server\\dist\\mcp\\server.js"]
    }
  }
}

Replace C:\path\to\example-mcp-server with the actual full path to your project.

macOS

  1. Open ~/Library/Application Support/Claude/claude_desktop_config.json

  2. Add the server configuration (use POSIX paths)

Linux

  1. Open ~/.config/Claude/claude_desktop_config.json

  2. Add the server configuration

Example Configuration

{
  "mcpServers": {
    "example-mcp-server": {
      "command": "node",
      "args": ["C:\\Users\\YourUsername\\projects\\example-mcp-server\\dist\\mcp\\server.js"]
    }
  }
}
  1. Restart Claude Desktop for the changes to take effect

  2. In Claude, look for the tool icon or mention "use the ping tool" or "check system info"

Adding New Tools

To add a new tool:

  1. Create a tool file in src/tools/ (e.g., src/tools/my_tool.ts):

import { ToolHandler } from "../types/index.js";

export const myToolHandler: ToolHandler = async (args) => {
  // Implement your tool logic
  return { result: "Your result here" };
};

export const myToolDefinition = {
  name: "my_tool",
  description: "Description of what your tool does",
  inputSchema: {
    type: "object",
    properties: {
      param1: { type: "string", description: "First parameter" },
      param2: { type: "number", description: "Second parameter" },
    },
    required: ["param1"],
  },
};
  1. Register it in src/tools/index.ts:

import { myToolHandler, myToolDefinition } from "./my_tool.js";

const registry: ToolRegistry = {
  // ... existing tools
  my_tool: {
    definition: myToolDefinition,
    handler: myToolHandler,
  },
};
  1. Rebuild and restart:

npm run build
npm start

MCP Protocol Overview

The server implements the MCP specification with support for:

  • initialize: Handshake with client

  • tools/list: Returns available tools and schemas

  • tools/call: Executes a tool with provided arguments

All communication uses JSON-RPC 2.0 format with structured error handling.

Troubleshooting

Server won't start

  • Ensure Node.js 18+ is installed: node --version

  • Check TypeScript compiled correctly: npm run build

  • Verify dist/mcp/server.js exists

Claude Desktop doesn't see the server

  • Double-check the path in claude_desktop_config.json is correct and absolute

  • Restart Claude Desktop after updating config

  • Check server runs locally: npm start

Tool calls fail

  • Ensure tool name matches exactly (case-sensitive)

  • Verify required parameters are provided

  • Check error message in JSON-RPC response

Scripts

npm run build    # Compile TypeScript to dist/
npm start        # Run the MCP server
npm run dev      # Build and run in one command

License

MIT

References

Available Tools

4 tools
file_readerC

Read the contents of a file from the filesystem

Inputs: path (required), encoding.

git_statusB

Check the status of a git repository, including current branch, changed files, and commit history

Inputs: path.

pingA

A simple health check tool that returns 'pong'

Inputs: no named parameters.

system_infoA

Returns system and platform information (OS type, memory, CPU, Node.js version)

Inputs: no named parameters.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    B3.4/5.0

    Scored across 4 tools

    Disambiguation5/5

    Each tool has a clearly distinct purpose: health check, system information, git status, and file reading. There is no meaningful overlap that would cause misselection.

    Naming Consistency3/5

    Names are all lowercase snake_case and readable, but they mix grammatical forms: 'ping' is a bare verb, while the others are noun/noun-phrase style tools. The inconsistency is minor but noticeable.

    Tool Count5/5

    Four tools is well within a reasonable range for a small utility server. Each tool covers a distinct diagnostic or file-access operation without bloat.

    Completeness3/5

    The surface covers basic read-only diagnostics, but it lacks write/update operations such as file writing or git mutations. For a general utility server, these are notable gaps, though basic inspection workflows are covered.

    Maintenance

    ActivityInactive
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers

    • -
      license
      B
      quality
      Not graded
      maintenance
      A boilerplate project for quickly developing Model Context Protocol (MCP) servers using TypeScript SDK. Includes example tools for calculations and greetings, plus system information resources.
      3
      -
    • A
      license
      B
      quality
      D
      maintenance
      A boilerplate project for quickly developing Model Context Protocol (MCP) servers using TypeScript SDK. Includes example tools like calculator and greeting functions, plus system information resources.
      3
      ISC
    • A
      license
      Not graded
      quality
      D
      maintenance
      A Node.js/TypeScript MCP server template with sample tools (ping and system_info) that demonstrates how to build custom tools for Claude Desktop using stdio transport.
      MIT
    • A
      license
      Not graded
      quality
      D
      maintenance
      A TypeScript-based Model Context Protocol server that enables Claude Desktop to fetch real-time weather data via external weather APIs. It provides a simple integration for users to query current weather information through natural language interactions.
      ISC