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
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
- Clone or navigate to the project directory:
cd example-mcp-server
- Install dependencies:
npm install
- 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
- Open
%APPDATA%\Claude\claude_desktop_config.json - 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
- Open
~/Library/Application Support/Claude/claude_desktop_config.json - Add the server configuration (use POSIX paths)
Linux
- Open
~/.config/Claude/claude_desktop_config.json - Add the server configuration
Example Configuration
{
"mcpServers": {
"example-mcp-server": {
"command": "node",
"args": ["C:\\Users\\YourUsername\\projects\\example-mcp-server\\dist\\mcp\\server.js"]
}
}
}
- Restart Claude Desktop for the changes to take effect
- 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:
- 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"],
},
};
- 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,
},
};
- 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.jsexists
Claude Desktop doesn't see the server
- Double-check the path in
claude_desktop_config.jsonis 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