nrf-mcp

MCP server for Nordic nRF Connect SDK development. Provides Claude with tools to browse documentation and sample code from the nrfconnect/sdk-nrf repository.

Tools

Search examples

# Find all uses of a symbol
DFU_TARGET_IMAGE_TYPE_ANY

# Search docs only
FOTA path:doc/nrf

# Search samples only
peripheral_hr path:samples

# Filter by file type
CONFIG_BT_PERIPHERAL extension:conf
bt_le_adv_start extension:c

Recursive directory listing

Use depth to get a full project overview in one call:

{ "path": "samples/bluetooth/central_bas", "depth": 2 }

Reading specific line ranges

When working with large files, use startLine and endLine to read just the relevant section:

{ "path": "samples/bluetooth/central_bas/src/main.c", "startLine": 1, "endLine": 50 }

Paginating search results

Search returns up to 20 results per page. Use the page parameter to fetch more:

{ "query": "bt_le_adv_start extension:c", "page": 2 }

Comparing SDK versions

See what changed in a file between releases:

{ "path": "samples/bluetooth/central_bas/src/main.c", "fromRef": "v3.0.0", "toRef": "v3.2.4" }

Kconfig symbol lookup

Look up what a prj.conf option does:

{ "symbol": "CONFIG_BT_PERIPHERAL" }

Setup

Prerequisites

• Node.js 18+
• GitHub CLI (gh) authenticated — used to supply a GitHub token at runtime

Install and build

npm install
npm run build

Register with Claude Code

claude mcp add -s user nrf-mcp -- /path/to/nrf-mcp/run.sh

Register with Claude Desktop

Add to ~/Library/Application Support/Claude/claude_desktop_config.json:

{
  "mcpServers": {
    "nrf-mcp": {
      "command": "/path/to/nrf-mcp/run.sh",
      "args": []
    }
  }
}

Then restart Claude Desktop.

The run.sh wrapper fetches a fresh token from gh auth token each time the server starts, so no token is ever hardcoded.

Configuration

To target a different SDK version, set the env var in the MCP registration:

claude mcp remove nrf-mcp
claude mcp add -s user -e NRF_SDK_REF=v3.2.4 nrf-mcp -- /path/to/nrf-mcp/run.sh

Rebuild after changes

npm run build

During development, use npm run watch to recompile automatically on save.

Testing

Run the end-to-end test suite (requires gh to be authenticated):

npm test

The tests spawn the server via run.sh, exercise all five tools (including recursive listing, line ranges, pagination, snippets, diff, Kconfig lookup, and error handling), and validate input error handling.

Troubleshooting

gh: command not found or empty token The run.sh script fetches a token via gh auth token. Make sure the GitHub CLI is installed and you are logged in:

gh auth login
gh auth token   # should print a token

GitHub API 401 errors nrf_search requires authentication. If the token is missing or expired, re-authenticate with gh auth login. For Claude Desktop, ensure run.sh is executable (chmod +x run.sh) — it prepends the Homebrew bin path to find gh.

GitHub rate limit exceeded Unauthenticated requests are limited to 60/hour. With a valid GITHUB_TOKEN the limit is 5 000/hour. The server automatically retries on rate-limit errors with backoff (up to 30s). Ensure gh auth token returns a token and that run.sh is being used (not node dist/index.js directly).

Tools not appearing in Claude

• Claude Code: run claude mcp list to confirm nrf-mcp is registered, then restart the session.
• Claude Desktop: restart the app after editing claude_desktop_config.json. Check the Desktop developer console for MCP startup errors.

Stale results Directory listings and file contents are cached in memory for 5 minutes to reduce API calls. Restart the server to clear the cache.

Wrong SDK version Confirm the active ref with echo $NRF_SDK_REF in the same shell, or check what's registered:

claude mcp list   # shows the -e env vars set at registration time

To change it, remove and re-add the registration with the new -e NRF_SDK_REF= value.