Mender MCP Server

Model Context Protocol (MCP) server for seamless Mender IoT platform integration with AI assistants.

Overview

The Mender MCP Server enables AI assistants like Claude Code to interact directly with your Mender IoT platform for device management, deployment tracking, and system monitoring. Through natural language commands, you can manage your IoT devices, monitor deployments, and troubleshoot issues without leaving your development environment.

✨ Key Features

• 🔍 Device Management: List, filter, and monitor IoT device status across your fleet

• 🚀 Deployment Tracking: Monitor deployment progress, success rates, and failure analysis

• 📊 Real-time Monitoring: Check device inventory, hardware specs, and system attributes

• 📝 Deployment Logs: Access detailed logs for failed deployments and troubleshooting

• 🏷️ Release Management: Browse releases, artifacts, and compatibility information

• 🔒 Enterprise Security: Token-based authentication with comprehensive input validation

• 📋 Read-only Operations: Safe monitoring without risk of accidental device control

• 🌐 Multi-platform Support: Works with hosted Mender and on-premise installations

🚀 Quick Start

1. Installation

Prerequisites

• Python 3.8+ installed on your system

• Active hosted Mender account

• Claude Code or other AI agent capable of using MCP

Install from Source

Verify Installation

2. Mender Authentication Setup

Get Your Personal Access Token

1. Log into hosted Mender:

   • Go to hosted.mender.io (or your on-premise URL)

   • Sign in with your Mender account credentials

2. Navigate to Settings:

   • Click your profile/avatar in the top right

   • Select "Settings" from the dropdown menu

3. Create Personal Access Token:

   • Go to "Personal Access Tokens" tab

   • Click "Generate new token"

   • Token Name: mender-mcp-integration (or descriptive name)

   • Permissions Required:

     • ✅ Device Management - Read device status, inventory, and attributes

     • ✅ Deployment Management - Read deployment status and history

     • ✅ Artifact Management - View artifacts and releases (optional)

     • ✅ Device Logs - Access deployment logs (optional, if available)

4. Save Your Token:

   • Copy the generated token immediately (it won't be shown again)

   • Store it securely using one of the methods below

Token Storage Options

Option 1: Environment Variable (Recommended)

Option 2: Secure Token File

3. Claude Code Integration

Add to Claude Code Configuration

1. Open Claude Code Settings:

   • In Claude Code, go to Settings → MCP Servers

   • Or edit your MCP configuration file directly

2. Add Mender MCP Server:

Using Environment Variable (Recommended):

Using Token File:

For On-Premise Mender:

3. Restart Claude Code to load the new MCP server configuration.

💬 Usage Examples

Once configured, you can interact with your Mender devices using natural language in Claude Code:

Device Management

Deployment Monitoring

Device Inventory & Hardware

Release & Artifact Management

Troubleshooting & Logs

Fleet Analysis & Monitoring

Security & Compliance Monitoring

Operational Intelligence

Audit Logs

Automated Workflows

Custom Logging & Debugging

Enable debug logging:

🔧 Command Line Interface

You can also run the server directly for testing:

📋 Available Tools & Resources

MCP Tools (Actions)

• get_device_status: Get current status of a specific device

• list_devices: List devices with filtering (status, device type, limit)

• get_deployment_status: Check deployment progress and details

• list_deployments: List deployments with status filtering

• get_deployment_device_log: Get deployment logs for a specific device

• get_deployment_logs: Get deployment logs for all devices in a deployment

• get_release_status: Get detailed information about a specific release

• list_releases: List releases with filtering (name, tag, limit)

• get_device_inventory: Get complete inventory attributes for a device

• list_device_inventory: List device inventories with filtering

• get_inventory_groups: Get all device inventory groups

• get_audit_logs: Get Mender audit logs with comprehensive filtering (user, action, date range, object type)

MCP Resources (Data Access)

• mender://devices: Complete device inventory

• mender://deployments: All deployments

• mender://artifacts: Available artifacts

• mender://releases: Complete release catalog

• mender://inventory: Device inventory with hardware specs and custom attributes

• mender://inventory-groups: Device grouping information

• mender://audit-logs: System audit logs for user actions and system changes

• mender://devices/{device_id}: Specific device details

• mender://deployments/{deployment_id}: Specific deployment details

• mender://releases/{release_name}: Specific release details

🔒 Security & Best Practices

Token Security

• ✅ Use environment variables or secure token files (not direct configuration)

• ✅ Set appropriate permissions on token files (chmod 600 ~/.mender/token)

• ✅ Rotate tokens regularly (quarterly recommended for production)

• ✅ Use minimal required permissions (Device Management, Deployment Management)

• ❌ Never commit tokens to version control or share in plain text

Performance Considerations

• API rate limits: Respect Mender's API limits with reasonable request frequencies

• Fleet size scaling: Use appropriate limit values for large device fleets

• Timeout settings: Adjust timeouts for large deployments and slow networks

• Memory usage: Monitor memory consumption with 1000+ device fleets

🐛 Troubleshooting

Common Issues

Authentication Errors:

• Verify your Personal Access Token is valid and not expired

• Check token has Device Management and Deployment Management permissions

• Ensure token is properly formatted (no extra spaces or newlines)

Permission Errors:

• Add required permissions: Device Management, Deployment Management

• Contact your Mender admin to verify account access levels

• Check if organization access is properly configured

Connection Issues:

• Verify Mender server URL is correct (https://hosted.mender.io)

• Check network connectivity and firewall settings

• Confirm DNS resolution works for your Mender server

• Test with browser access to the same URL

Configuration Problems:

• Ensure virtual environment is activated: source venv/bin/activate

• Verify installation completed successfully: pip install -e .

• Check PATH includes the virtual environment's bin directory

Deployment Logs Issues

"No deployment logs found":

• This is normal for successful deployments (logs typically only retained for failures)

• Failed deployments should have detailed logs available

• Some Mender configurations don't enable deployment logging by default

Empty or truncated logs:

• Large deployments may have truncated logs due to size limits

• Check device-side logs for more detailed information

• Consider deployment size and timeout settings

Getting Help

1. Check server connectivity: Test with mcp-server-mender --help

2. Verify Mender access: Log into Mender web interface with same credentials

3. Test token manually: Use Mender API documentation to test token directly

4. Enable debug logging: Set MCP_LOG_LEVEL=DEBUG for detailed output

5. Review Claude Code logs: Check Claude Code's MCP connection status

🧪 Development & Testing

Running Tests

📝 License

MIT License - see LICENSE file for details.

🤝 Contributing

Contributions are welcome! Please read our contributing guidelines and submit pull requests for any improvements.

📞 Support

• Documentation: This README and inline help (--help)

• Issues: GitHub Issues for bug reports and feature requests

• Community: Mender Community Hub for general IoT device management discussions