vesc-mcp

vesc-mcp gives MCP-compatible assistants reliable, local access to VESC firmware and .vescpkg knowledge. It can search the bundled knowledge base, inspect and validate package files, and build packages with VESC Tool.

Its knowledge scope includes current VESC behavior plus historical codepaths, versions, bugs, and architecture. That historical VESC coverage is corpus content, not a reason to retain obsolete vesc-mcp APIs or storage formats. Future retrieval may also support VESC-aware code review.

It does not discover devices, upload packages, or flash firmware.

Install

Download the release archive for your operating system and CPU from the Releases page, then extract the complete archive. Keep the executable and its bundled support files together.

The executable is named vesc-mcp-server on Ubuntu and macOS, and vesc-mcp-server.exe on Windows. See the installation guide for platform-specific steps.

Choose a connection

vesc-mcp supports two MCP connections:

Connection	Best for	Available tools
stdio	One local assistant that needs package files	All configured tools
Streamable HTTP	Multiple clients sharing knowledge search and package work	Knowledge tools, resources, and authenticated package tools plus feedback writes when configured

Unauthenticated Streamable HTTP remains read-only for knowledge and resources. Authenticated HTTP clients can use package tools, sandboxed to configured roots plus the client's advertised local file:// roots.

Streamable HTTP quick start

From the extracted release directory, run:

VESC_MCP_WORKSPACE_ROOT="$PWD" ./vesc-mcp-server --http

On Windows PowerShell, run:

$env:VESC_MCP_WORKSPACE_ROOT = (Get-Location).Path
.\vesc-mcp-server.exe --http

The local endpoint is http://127.0.0.1:8080/mcp. Add it to a client that supports MCP Streamable HTTP:

{
  "mcpServers": {
    "vesc-mcp": {
      "type": "streamable-http",
      "url": "http://127.0.0.1:8080/mcp"
    }
  }
}

Client schemas differ; some clients infer the connection type from url and do not use the type field. The Streamable HTTP guide covers authentication, browser origins, remote access, and Windows commands.

Local stdio quick start

Point your MCP client at the executable from the extracted release. A typical configuration is:

{
  "mcpServers": {
    "vesc-mcp": {
      "command": "/path/to/vesc-mcp-server",
      "env": {
        "VESC_MCP_WORKSPACE_ROOT": "/path/to/extracted/vesc-mcp",
        "VESC_PACKAGE_ROOTS": "/path/to/your/vesc-packages"
      }
    }
  }
}

Use vesc-mcp-server.exe and Windows paths on Windows. Prefer config.toml for Windows package roots so drive-letter colons are not interpreted as path separators.

After connecting, call ping, then try search_vesc_knowledge. For package work, start with list_vesc_packages and inspect_pkgdesc.

To let the model retain reusable lessons and evidence-backed corrections, set a durable feedback directory and explicitly enable writes:

export VESC_RAG_FEEDBACK_PATH="$PWD/.vesc-mcp-feedback"
export VESC_RAG_FEEDBACK_WRITES=true

HTTP feedback writes additionally require VESC_MCP_HTTP_AUTH_TOKEN; unauthenticated and unconfigured connections remain read-only.

What it provides

Tool	Purpose
ping	Verify the server connection
search_vesc_knowledge	Search VESC knowledge, returning relevant corrections before ordinary results
submit_vesc_knowledge_feedback	Save a reusable but explicitly unverified lesson
correct_vesc_knowledge	Persist a user-authorized, evidence-backed correction plus the failed retrieval trace and knowledge-gap diagnosis
replay_vesc_knowledge_correction	Replay the preserved query