Leshan MCP Server

A standards-compliant Model Context Protocol (MCP) server for Leshan LwM2M, exposing Leshan device management as MCP tools. This server allows you to connect Leshan-managed IoT devices to any MCP-compatible client (e.g., Claude Desktop, Cursor, etc.).

Features

• Standards-compliant MCP server implementation
• Exposes Leshan LwM2M device management as MCP tools
• Easy CLI usage via npx or as a global tool
• Configurable Leshan backend connection
• Proper error handling and timeout protection
• Comprehensive logging with development/production modes
• Built-in health checks and connection monitoring

Installation

With npx (recommended):

npx leshan-mcp-server

As a global CLI:

npm install -g leshan-mcp-server
leshan-mcp-server

As a local dependency:

npm install leshan-mcp-server
npx leshan-mcp-server

Configuration

Configure the Leshan backend URL with environment variables:

export LESHAN_HOST="localhost"
export LESHAN_PORT="8084"
export LESHAN_API_BASE="/api"

Default values:

• LESHAN_HOST: localhost
• LESHAN_PORT: 8080
• LESHAN_API_BASE: /api
• LESHAN_TIMEOUT: 30000 (30 seconds)
• MAX_CONCURRENT_REQUESTS: 10

Usage

Production Mode (MCP Compliant - No Logging):

npx leshan-mcp-server

Development Mode (With Debug Logging):

NODE_ENV=development npx leshan-mcp-server

With Custom Configuration:

LESHAN_HOST=192.168.1.100 LESHAN_PORT=8084 npx leshan-mcp-server

MCP Client Integration

Claude Desktop

Add to your claude_desktop_config.json:

{
  "mcpServers": {
    "leshan": {
      "command": "npx",
      "args": ["leshan-mcp-server"],
      "env": {
        "LESHAN_HOST": "localhost",
        "LESHAN_PORT": "8084"
      }
    }
  }
}

Testing with MCP Inspector

npx @modelcontextprotocol/inspector npx leshan-mcp-server

Available Tools

list-devices

List all registered LwM2M devices

• Parameters: None
• Returns: Array of device information

get-device-info

Get detailed information about a specific device

• Parameters: { deviceId: string }
• Returns: Device details including registration info

read-resource

Read a resource value from a device

• Parameters: { deviceId: string, objectId: string, instanceId: string, resourceId: string }
• Returns: Resource value and metadata

write-resource

Write a value to a device resource

• Parameters: { deviceId: string, objectId: string, instanceId: string, resourceId: string, value: any }
• Returns: Write operation result

observe-resource

Start observing a resource for changes

• Parameters: { deviceId: string, objectId: string, instanceId: string, resourceId: string }
• Returns: Observation setup confirmation

cancel-observation

Cancel an active observation

• Parameters: { deviceId: string, objectId: string, instanceId: string, resourceId: string }
• Returns: Cancellation confirmation

execute-resource

Execute a resource on a device

• Parameters: { deviceId: string, objectId: string, instanceId: string, resourceId: string, arguments?: any }
• Returns: Execution result

Available Prompts

device-diagnostics

Generate comprehensive device diagnostic reports

• Parameters: { deviceId: string }

device-monitoring

Set up monitoring dashboards for devices

• Parameters: { deviceIds: string[], monitoringType: string }

lwm2m-troubleshooting

Troubleshoot LwM2M connectivity and protocol issues

• Parameters: { deviceId: string, issueType: string }

device-configuration

Configure device settings and parameters

• Parameters: { deviceId: string, configurationType: string }

Error Handling

The server includes comprehensive error handling:

• Connection timeouts and retries
• Proper HTTP status code handling
• Detailed error logging in development mode
• Graceful degradation for network issues

Logging

• Production: Silent operation (MCP compliant)
• Development: Detailed JSON logs with timestamps
• Health checks: Automatic connection monitoring
• Request tracking: Operation IDs for debugging

Requirements

• Node.js 16+
• Access to a running Leshan LwM2M server
• Network connectivity to Leshan server

Troubleshooting

Connection Issues

1. Verify Leshan server is running: curl http://localhost:8084/api/clients
2. Check environment variables are set correctly
3. Ensure network connectivity between MCP server and Leshan

404 Errors

• Verify LESHAN_API_BASE matches your Leshan server configuration
• Check if Leshan server uses different API endpoints

MCP Inspector Issues

• Use CLI inspector: npx @modelcontextprotocol/inspector npx leshan-mcp-server
• Web inspector may have connection issues with stdio transport

License

MIT

Contributing

Pull requests and issues are welcome! Please ensure all tests pass and follow the existing code style.

Repository

https://github.com/yourusername/leshan-mcp-server