MCP Zephyr West Context Server

A Model Context Protocol (MCP) server for analyzing Zephyr RTOS and West workspace directories. This server provides structured information about embedded development projects using Zephyr, making it easier for AI assistants to understand and work with firmware projects.

Features

• West Workspace Analysis: Validates and analyzes West-managed Zephyr workspaces
• Version Detection: Extracts Zephyr RTOS and SDK versions (including Nordic Connect SDK)
• Component Discovery: Finds and catalogs modules, boards, and projects
• Build System Information: Identifies Kconfig files, CMake modules, and toolchain configurations
• Manifest Parsing: Reads West manifest files to understand project structure
• ⭐ Kconfig Verification: Verify if Kconfig options are available before implementation (NEW!)

Prerequisites

• Node.js (v14 or higher)
• npm (Node Package Manager)
• A Zephyr/West workspace to analyze

Installation

Install the package globally using npm:

npm install -g mcp-zephyr

Or install locally in your project:

npm install mcp-zephyr

Setup for Claude Desktop

Option 1: Using Claude MCP CLI (Recommended)

The easiest way to add this MCP server to Claude Desktop:

claude mcp add mcp-zephyr

Option 2: Manual Configuration

To manually configure this MCP server with Claude Desktop:

1. Open your Claude Desktop configuration file:

   • macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
   • Windows: %APPDATA%\Claude\claude_desktop_config.json
   • Linux: ~/.config/Claude/claude_desktop_config.json

2. Add the MCP Zephyr server to the mcpServers section:

If installed globally:

{
  "mcpServers": {
    "mcp-zephyr": {
      "command": "mcp-zephyr",
      "env": {}
    }
  }
}

If installed locally:

{
  "mcpServers": {
    "mcp-zephyr": {
      "command": "npx",
      "args": ["mcp-zephyr"],
      "env": {}
    }
  }
}

3. Restart Claude Desktop for the changes to take effect.

Available Tools

Once configured, the following tools will be available in Claude:

analyze_workspace

Performs a complete analysis of a West workspace directory.

Parameters:

• path (string): Path to the West workspace directory (containing .west folder)
• westPath (string, optional): Custom path to the .west directory (defaults to path/.west)

Returns: Comprehensive analysis including version info, modules, boards, and build configuration.

get_zephyr_version

Extracts the Zephyr RTOS version from a workspace.

Parameters:

• path (string): Path to the West workspace directory
• westPath (string, optional): Custom path to the .west directory (defaults to path/.west)

Returns: Version information including major, minor, patch, and full version string.

list_modules

Lists all modules discovered in the workspace.

Parameters:

• path (string): Path to the West workspace directory
• westPath (string, optional): Custom path to the .west directory (defaults to path/.west)

Returns: List of modules with their paths, categories, and capabilities (CMake/Kconfig support).

get_manifest_info

Retrieves and parses the West manifest information.

Parameters:

• path (string): Path to the West workspace directory
• westPath (string, optional): Custom path to the .west directory (defaults to path/.west)

Returns: Manifest details including remotes, projects, and defaults.

list_boards

Finds all available hardware boards in the workspace.

Parameters:

• path (string): Path to the West workspace directory
• westPath (string, optional): Custom path to the .west directory (defaults to path/.west)

Returns: List of boards grouped by architecture or vendor.

get_build_info

Gets build system information including CMake and Kconfig files.

Parameters:

• path (string): Path to the West workspace directory
• westPath (string, optional): Custom path to the .west directory (defaults to path/.west)

Returns: Lists of Kconfig files, CMake modules, and toolchain configurations.

verify_kconfigs ⭐ NEW

Verifies if specified Kconfig options are available in the workspace before implementation. This prevents coding against non-existent configurations and provides alternatives and suggestions.

Parameters:

• path (string): Path to the West workspace directory
• kconfigs (array): List of Kconfig option names to verify (e.g., ["BT_PERIPHERAL", "BT_NUS", "BT_AUDIO"])
• westPath (string, optional): Custom path to the .west directory (defaults to path/.west)

Returns: Comprehensive verification report including:

• ✅ Available configs with source files, descriptions, and dependencies
• ❌ Missing configs with alternatives and implementation suggestions
• ⚠️ Warnings about deprecated or conditional configs
• 📋 Implementation recommendations

Example Usage:

"Please verify if these BLE Kconfigs are available: BT_PERIPHERAL, BT_NUS, BT_AUDIO, BT_HRS"

Usage Examples

After setup, you can ask Claude to analyze your Zephyr workspace:

"Can you analyze my Zephyr workspace at /home/user/zephyrproject?"

"What version of Zephyr is in /path/to/workspace?"

"List all the boards available in my West workspace"

"Show me the modules in my Nordic Connect SDK project"

Custom .west Directory Location

If your .west directory is not located in the standard workspace/.west location, you can specify a custom path:

"Analyze my workspace at /home/user/project with the .west directory at /home/user/custom/.west"

The tools accept an optional westPath parameter for non-standard West configurations.

Testing

You can test the MCP server directly:

# If installed globally
mcp-zephyr

# If installed locally  
npx mcp-zephyr

The server will start and wait for MCP protocol messages via stdin/stdout.

Project Structure

mcp-zephyr/
├── src/
│   ├── index.js      # MCP server implementation
│   └── analyzer.js   # West workspace analyzer
├── package.json      # Node.js dependencies and metadata
├── LICENSE          # MIT license
└── README.md        # This documentation

How It Works

1. Workspace Validation: Checks for .west/config to confirm a valid West workspace
2. Configuration Parsing: Reads West configuration to understand workspace structure
3. Manifest Analysis: Parses west.yml to identify projects and dependencies
4. Component Discovery: Scans for:
   • Zephyr version files
   • SDK versions (Nordic Connect SDK, etc.)
   • Hardware board definitions
   • Module directories
   • Build system files (Kconfig, CMake)
5. Structured Output: Returns organized information for AI consumption

Supported Workspace Types

• Zephyr RTOS standalone workspaces
• Nordic Connect SDK (NCS) workspaces
• Custom West-managed projects
• Multi-repository Zephyr projects

Troubleshooting

Server doesn't start

• Ensure Node.js is installed: node --version
• Verify the package is installed: npm list -g mcp-zephyr (for global) or npm list mcp-zephyr (for local)
• Check your Claude Desktop configuration syntax (valid JSON)

Workspace not recognized

• Confirm the workspace has a .west directory
• Check that the workspace was initialized with west init
• Ensure you're pointing to the workspace root, not a subdirectory

Tools not appearing in Claude

• Restart Claude Desktop after configuration changes
• Check the configuration file syntax (valid JSON)
• Try using claude mcp list to see if the server is registered
• Look for errors in Claude's developer console

License

MIT

Contributing

Contributions are welcome! Please feel free to submit issues or pull requests to improve the analyzer's capabilities or add support for additional Zephyr/West features.