# 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
1. **Clone or navigate to the project directory:**
```bash
cd example-mcp-server
```
2. **Install dependencies:**
```bash
npm install
```
3. **Build the TypeScript code:**
```bash
npm run build
```
This compiles all `.ts` files in `src/` to JavaScript in the `dist/` folder.
### Running the MCP Server
```bash
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:
```powershell
$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`:
```javascript
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:
```bash
npm run build && node test.js
```
## Available Tools
### 1. `ping`
A simple health check tool.
**Request:**
```json
{
"jsonrpc": "2.0",
"id": 1,
"method": "tools/call",
"params": {
"name": "ping",
"arguments": {}
}
}
```
**Response:**
```json
{
"jsonrpc": "2.0",
"id": 1,
"result": {
"output": "pong"
}
}
```
### 2. `system_info`
Returns system and platform information.
**Request:**
```json
{
"jsonrpc": "2.0",
"id": 2,
"method": "tools/call",
"params": {
"name": "system_info",
"arguments": {}
}
}
```
**Response:**
```json
{
"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:
```json
{
"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
```json
{
"mcpServers": {
"example-mcp-server": {
"command": "node",
"args": ["C:\\Users\\YourUsername\\projects\\example-mcp-server\\dist\\mcp\\server.js"]
}
}
}
```
3. **Restart Claude Desktop** for the changes to take effect
4. 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`):
```typescript
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"],
},
};
```
2. **Register it in `src/tools/index.ts`**:
```typescript
import { myToolHandler, myToolDefinition } from "./my_tool.js";
const registry: ToolRegistry = {
// ... existing tools
my_tool: {
definition: myToolDefinition,
handler: myToolHandler,
},
};
```
3. **Rebuild and restart**:
```bash
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
```bash
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
- [Model Context Protocol Documentation](https://modelcontextprotocol.io/)
- [Claude Desktop Integration](https://support.anthropic.com/)
- [JSON-RPC 2.0 Specification](https://www.jsonrpc.org/specification)
