Buttplug MCP

1 day ago 8

Buttplug MCP는 Buttplug.io 생태계 내 성인용 디바이스를 대형 언어 모델(LLM) 기반 프로그램과 연동하는 MCP 서버임
사용자는 Claude Desktop 등 LLM 툴을 통해 디바이스 정보를 조회하거나 진동, 배터리 상태, 신호 세기 등 다양한 기능 제어가 가능함
현재는 기능적 완성도와 안정성이 부족해 전체 기능이 매끄럽지 않고, 실제 디바이스 제어에 어려움이 있음
Ollama, mcphost 등 MCP 호스트와 연동하여 툴 기반의 테스트가 가능하나, 일부 기능(자원 탐색 등)은 제한됨
이 프로젝트는 다른 MCP 서비스와 비교해 LLM-기반 스마트 디바이스 제어에 특화되어 있으며 오픈소스로 무료 제공됨

프로젝트 개요

buttplug-mcp는 Model Context Protocol(MCP) 서버로, Buttplug.io 생태계 전용임
Claude Desktop과 같은 툴 지원 LLM 프로그램에서 자신의 Buttplug 디바이스를 질의·제어 가능함
- 예시 명령: "내 연결된 buttplug 디바이스는?", "LELO F1S의 두 번째 모터를 50%로", "Lovense Max 2의 배터리 잔량은?", "WeWibe 신호 약함 여부?"
위 예시는 목표 방향에 가깝지만, 실제 구현된 현재 경험은 불안정하고 실망스러운 상태임

지원 리소스 및 툴 구조

API 리소스
- /devices: 연결된 Buttplug 디바이스 리스트(JSON)
- /device/{id}: 디바이스 개별 상세 정보
- /device/{id}/rssi: 디바이스 신호 세기(RSSI)
- /device/{id}/battery: 디바이스 별 배터리 잔량
툴
- device_vibrate: id, motor, strength 파라미터(필수: id, strength), 선택적으로 모터 지정해 진동을 제어

JSON 스키마 예시(리소스)

{ "resources": [ { "uri": "devices", "name": "Device List", "description": "List of connected Buttplug devices in JSON", "mimeType": "application/json" } ] }

JSON 스키마 예시(툴)

{ "tools": [ { "description": "Vibrates device by `id`, selecting `strength` and optional motor", "inputSchema": { "type": "object", "properties": { "id": {"description": "Device ID to query, sourced from `/devices`", "type": "number"}, "motor": {"description": "Motor number to vibrate, defaults to 0", "type": "number"}, "strength": {"description": "Strength from 0.0 to 1.0, with 0.0 being off and 1.0 being full", "type": "number"} }, "required": ["id", "strength"] }, "name": "device_vibrate" } ] }

현재 상태

2025년 4월 1일(만우절)에 시작한 실험적 단기 프로젝트임
go-buttplug 라이브러리의 연결 관리가 불안정해, 디바이스 리스트 질의는 되나 진동 기능 등 일부 제어가 원활하지 않음
테스트 목적으로 가상 디바이스가 필요하나 Buttplug.io는 물리적 디바이스만 지원함
엔드투엔드 테스트가 충분히 이뤄지지 않은 초기 단계임
향후 go-buttplug 라이브러리의 연결 문제와 MCP 프로토콜의 호스트 상태(툴 중심 구현 등)를 추가로 검토할 예정임

설치 안내

다중 플랫폼용 바이너리 파일이 GitHub Releases에 배포됨
Homebrew를 통한 설치도 지원됨:
- brew tap conacademy/homebrew-tap
- brew install conacademy/tap/buttplug-mcp

사용법

디바이스 관리는 Intiface Central 허브 앱에서 담당(기본 포트 12345)
Claude Desktop에서 MCP 서버로 buttplug-mcp를 사용할 수 있도록 호스트 프로그램에 설정 필요
- 예시 설정(JSON 파일):
{ "mcpServers": { "buttplug": { "command": "/opt/homebrew/bin/buttplug-mcp", "args": ["--ws-port", "12345"] } } }
위 설정 후 Claude Desktop의 튜토리얼을 참고하여 적용 가능, Claude와 대화하며 디바이스 질의·제어 가능
HomeAssistant MCP를 통한 조명 제어 등 추가 연동 활용 가능

Ollama 및 mcphost와의 통합

MCP 호스트 중 Ollama 지원이 가능하며, 툴 지원 LLM과 연동 가능
mcphost(mcp-go 개발자가 관리)와 함께 buttplug-mcp용 MCP JSON 설정으로 사용 가능
- 예시:
$ go install github.com/mark3labs/mcphost@latest $ mcphost -m ollama:llama3.3 --config mcp.json
"Tools"만 지원하고 "Resources"는 제한되어 디바이스 나열이나 속성 탐색 불가
실제 예시에서는 디바이스 진동 명령에 대한 성공 메시지는 반환하지만, 디바이스 반응이 없을 수 있음

빌드

task 기반 빌드 시스템 적용
- 실행: $ task
유용한 테스트 도구:
- task stdio-schema | jq (JSON 스키마 확인)
- npx @modelcontextprotocol/inspector node build/index.js (MCP Inspector Web GUI)

CLI 인자

주요 옵션:
- -h, --help: 도움말
- -l, --log-file: 로그파일 목적지 지정
- -j, --log-json: JSON 로그 형식
- --sse: SSE 전송 사용
- --sse-host: SSE 연결용 호스트/포트
- -v, --verbose: 상세 로그
- --ws-port: Buttplug Websocket 서버 접속 포트

기여 및 코드 오브 컨덕트

Pull Request, 포크 등 자유롭게 환영
Code of Conduct 준수 필요

크레딧 및 라이선스

go-buttplug, go-mcp 오픈소스 프로젝트 활용
- Buttplug.io Golang 라이브러리 및 예시, Model Context Protocol Golang 라이브러리 포함
2025 Neomantra BV, Evan Wies(ConAcademy) 저작
MIT 라이선스로 공개(자세한 라이선스는 LICENSE.txt 참고)

Read Entire Article