npm package: @max-mclaughlin/depthai-mcp-server
Description: MCP server for Luxonis DepthAI docs, examples, and forum context.
Latest version: 0.3.0

# Luxonis DepthAI MCP

`@max-mclaughlin/depthai-mcp-server` is a local MCP server for coding agents that need real Luxonis context when writing DepthAI code.

It indexes and searches:

- official Luxonis docs from `docs.luxonis.com`
- code and examples from `luxonis/oak-examples`
- public discussions from `discuss.luxonis.com`

The server is built for local stdio MCP clients such as Codex, Cursor, and Claude Code.

## What V2 Adds

V2 is focused on turning the server from a Luxonis search MCP into a better app-building and troubleshooting MCP.

Highlights:

- faster startup with cached index reuse
- background refresh instead of blocking startup on full rebuild
- grouped `oak-examples` bundles instead of raw file-only hits
- app-oriented tools for example selection, app structure, pipeline planning, and debugging
- richer troubleshooting and migration workflows

## What V3 Adds

V3 expands the MCP beyond docs, `oak-examples`, and forum content by indexing high-value Luxonis repos that improve API grounding, migration help, model workflows, and ROS guidance.

Additional indexed repos:

- `luxonis/depthai-core`
- `luxonis/depthai-python`
- `luxonis/depthai-nodes`
- `luxonis/modelconverter`
- `luxonis/depthai-model-zoo`
- `luxonis/depthai-ros`
- `luxonis/depthai-ros-examples`

V3 is designed so the extra repos help when they are relevant without polluting the default “build a DepthAI app” search flow.

Recommended workflow:

1. use a task-specific tool first, such as `find_examples_for_task`, `find_model_integration_patterns`, or `find_ros_packages`
2. inspect the exact source with `get_example_bundle` or `get_source_document`
3. use `diagnose_depthai_issue` for debugging flows
4. use `search_depthai` as the broad fallback search

## What It Exposes

Tools:

- `search_depthai`
- `search_examples`
- `search_forum`
- `find_core_api_usage_examples`
- `find_legacy_v2_patterns`
- `find_model_conversion_guidance`
- `find_ros_examples_for_task`
- `find_depthai_nodes_patterns`
- `find_ros_packages`
- `get_source_document`
- `get_api_reference`
- `get_porting_guidance`
- `get_index_status`
- `refresh_index`
- `list_available_sources`
- `find_examples_for_task`
- `get_example_bundle`
- `suggest_depthai_app_structure`
- `suggest_pipeline_components`
- `diagnose_depthai_issue`
- `find_forum_threads_for_error`
- `find_model_integration_patterns`
- `compare_v2_v3_approach`

Resources:

- `luxonis://index/status`
- `luxonis://troubleshooting/guide`
- `luxonis://examples/categories`
- `luxonis://document/{id}`
- `luxonis://example-bundle/{id}`

Prompts:

- `design-depthai-pipeline`
- `debug-depthai-issue`
- `choose-depthai-example`
- `migrate-depthai-v2-to-v3`

Default indexed source families:

- `docs`
- `examples`
- `forum`

Additional source families available in V3:

- `depthai_core`
- `depthai_python_v2`
- `depthai_nodes`
- `modelconverter`
- `model_zoo`
- `ros`
- `ros_examples`

## Install

### Run With `npx`

```bash
npx --yes --package @max-mclaughlin/depthai-mcp-server depthai-mcp-server
```

### Local Development

```bash
npm install
npm run build
npm run index -- --force
npm run serve
```

## MCP Client Setup

### Codex

Add this server to `~/.codex/config.toml`:

```toml
[mcp_servers.depthai]
command = "npx"
args = ["--yes", "--package", "@max-mclaughlin/depthai-mcp-server", "depthai-mcp-server"]
```

### Cursor

Add this to project-level `.cursor/mcp.json` or global Cursor MCP config:

```json
{
  "mcpServers": {
    "luxonis-depthai": {
      "command": "npx",
      "args": ["--yes", "--package", "@max-mclaughlin/depthai-mcp-server", "depthai-mcp-server"]
    }
  }
}
```

### Claude Code

```bash
claude mcp add-json luxonis-depthai '{"command":"npx","args":["--yes","--package","@max-mclaughlin/depthai-mcp-server","depthai-mcp-server"]}'
```

## Useful Commands

Build or rebuild the local search index:

```bash
depthai-mcp-server index build --force
```

Run the stdio server directly:

```bash
depthai-mcp-server serve
```

## Indexing And Cache Behavior

- The local index is stored at `~/.cache/depthai-mcp/index.json` by default.
- If an index already exists, the server uses it immediately on startup.
- The index is treated as stale after 24 hours.
- Stale indexes are refreshed in the background so MCP startup stays fast.
- You can force a rebuild with the `refresh_index` tool or `depthai-mcp-server index build --force`.

## Environment

- `DEPTHAI_MCP_CACHE_DIR`: override the cache directory. Default is `~/.cache/depthai-mcp`.

## Development Notes

- The docs and forum are crawled from public HTML and sitemap endpoints.
- `oak-examples` is downloaded from GitHub and indexed locally.
- Selected Luxonis repos are downloaded from GitHub tarballs and indexed as separate source families.
- The server is deliberately retrieval-first. It returns source-backed results instead of acting like a second chatbot.

## Publishing

Published package name:

- npm: `@max-mclaughlin/depthai-mcp-server`
- GitHub repo: `luxonis/depthai-mcp-server`

Recommended release flow:

```bash
npm run build
npm test
npm publish --access public
```

If the package name stays the same, users do not need to change their MCP config. They usually just need to restart Codex, Cursor, or Claude Code so `npx` pulls the newly published version.