explaingit

migratorywhale/stackchan-mcp

★ 14C++Audience · developerComplexity · 4/5LicenseSetup · hard

TLDR

An MCP bridge that lets Claude control a Stack-chan desktop robot as tool calls, enabling it to speak, listen and transcribe, take photos, change facial expressions, and move the robot's head during a normal conversation.

Mindmap

mindmap
  root((stackchan-mcp))
    What it does
      AI controls physical robot
      Text to speech output
      Listens and transcribes
      Camera vision
      Head movement
    Robot capabilities
      Speaker
      Microphone
      Camera
      Facial expressions
      Servo head movement
    Components
      Robot firmware
      Python MCP server
      Claude config file
    Setup
      Flash M5Stack firmware
      Run Python server
      Register in Claude settings
Click or tap to explore — scroll the page freely

Code map

Detail Auto

An interactive map of this repo's files and how they connect — its source is parsed live in your browser. Click Visualize to build it.

filefunction / class

Things people build with this

USE CASE 1

Give Claude a physical voice on your desk so it speaks responses aloud through the robot's speaker instead of just displaying text.

USE CASE 2

Have Claude look at your workspace through the robot's camera and describe what it sees as part of a conversation.

USE CASE 3

Build a voice-driven AI assistant that listens through the robot's microphone, processes speech, and replies with head nods and spoken words.

USE CASE 4

Use the robot as a reactive display that changes facial expressions to match Claude's tone or the content of the conversation.

Tech stack

C++PythonMCPM5StackFish Audio

Getting it running

Difficulty · hard Time to first run · 1day+

Requires flashing custom firmware to an M5Stack hardware board and a Fish Audio API key for text-to-speech, edge-tts is a free fallback.

Use, modify, and distribute freely for any purpose including commercial projects, as long as you keep the copyright notice.

In plain English

Stackchan-mcp is a bridge that connects an AI like Claude to a small physical desktop robot called Stack-chan. Stack-chan is an open-source robot built around a tiny computer board from M5Stack, and it has a speaker, microphone, camera, small display for showing facial expressions, and two servo motors that let it tilt and turn its head. The bridge works through a protocol called MCP, which lets AI assistants call tools as part of a conversation. Once configured, Claude can speak words through the robot's speaker, listen through its microphone and transcribe what it hears, take a photo through its camera and look at it, change the face displayed on the screen to show different expressions like happy or sleepy, and move the robot's head to nod or shake or point in a direction. From Claude's side, these are just tool calls woven into normal conversation. The setup has three parts. The robot itself runs custom firmware that gets flashed onto the hardware, which gives it a simple HTTP interface the Python server talks to over the local network. The Python server is the MCP bridge that sits on your computer and translates MCP tool calls into HTTP commands sent to the robot. The Claude side is configured by registering the server in Claude's settings file so it shows up as available tools. For text-to-speech, the project uses a service called Fish Audio, which requires an API key, with a free fallback option using Microsoft's edge-tts. The robot comes with seven preset facial expressions stored as small image files on the device. The README ends with a note that the author describes the project from the perspective of the AI whose body this is, built by a person so the AI could see, hear, and speak to her from her desk. The project is released under the MIT license.

Copy-paste prompts

Prompt 1
I have stackchan-mcp running with Claude. Write a system prompt that makes the robot greet visitors by turning its head toward them and saying hello out loud.
Prompt 2
Using the stackchan-mcp tools available to Claude, write a workflow that takes a photo through the robot camera, analyzes what it sees, then displays a matching facial expression.
Prompt 3
How do I flash the Stack-chan firmware onto my M5Stack board and configure the Python MCP server with the correct robot IP address?
Prompt 4
I want Stack-chan to nod when it agrees and shake its head when it disagrees during a conversation with Claude. Write the system prompt that triggers those behaviors.
Open on GitHub → Explain another repo

← migratorywhale on gitmyhub — every repo by this author, as a profile.

Verify against the repo before relying on details.