Skip to content
Back to search

buttplug-mcp

Buttplug.io Model Context Protocol (MCP) Server

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today
Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/conacademy--buttplug-mcp/badge.svg)](/listings/conacademy--buttplug-mcp)

HTML

<a href="/listings/conacademy--buttplug-mcp"><img src="/api/listings/conacademy--buttplug-mcp/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

Binaries for multiple platforms are [released on GitHub](https://github.com/conacademy/buttplug-mcp/releases) through [GitHub Actions](https://github.com/conacademy/buttplug-mcp/actions).

You can also install for various platforms with [Homebrew](https://brew.sh) from [`conacademy/homebrew-tap`](https://github.com/conacademy/homebrew-tap):

brew tap conacademy/homebrew-tap
brew install conacademy/tap/buttplug-mcp

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

README.md · README · 233 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

  1. # buttplug-mcp - Buttplug.io MCP Server
  2. `buttplug-mcp` is a [Model Context Protocol (MCP)](https://www.anthropic.com/news/model-context-protocol) server for the [Buttplug.io ecosystem](https://buttplug.io). It allows Tool-supporting LLM programs like [Claude Desktop](https://claude.ai/download) query and control your Genital Interface Devices.
  3. *|insert AI-generated slop image of robots doing nasty things|*
  4. <br>`LLM|=> - - (__(__)`
  5. Once set up, you can prompt your LLM:
  6. * "What are my connected buttplug devices?"
  7. * "Set the second motor on my LELO F1S to 50% strength"
  8. * "How much battery is left on my Lovense Max 2?"
  9. * "Does my WeWibe have weak signal?"
  10. **NOTE: The above is aspirational and really the [current experience](#current-state) is unstable and frustating.**
  11. It supports the following Resources and Tools:
  12. | Resource | Description |
  13. |----------|-------------|
  14. | `/devices` | List of connected Buttplug devices in JSON. |
  15. | `/device/{id}` | Device information by device ID where`id` is a number from `/devices` |
  16. | `/device/{id}/rssi` | RSSI signal level by device ID where `id` is a number from `/devices` |
  17. | `/device/{id}/battery` | Battery level by device ID where `id` is a number from `/devices` |
  18. | Tool | Params | Description |
  19. |------|--------|-------------|
  20. | `device_vibrate` | `id`, `motor`, `strength` | Vibrates device by `id`, selecting `strength` and optional `motor` |
  21. <details>
  22. <summary>JSON Schema for Resources. Click to expand</summary>
  23. [`schema_resources.json`](./schema_resources.json)
  24. ```
  25. {
  26. "jsonrpc": "2.0",
  27. "id": 1,
  28. "result": {
  29. "resources": [
  30. {
  31. "uri": "devices",
  32. "name": "Device List",
  33. "description": "List of connected Buttplug devices in JSON",
  34. "mimeType": "application/json"
  35. }
  36. ]
  37. }
  38. }
  39. ```
  40. </details>
  41. <details>
  42. <summary>JSON Schema for Tools. Click to expand</summary>
  43. [`schema_tools.json`](./schema_tools.json)
  44. ```
  45. {
  46. "jsonrpc": "2.0",
  47. "id": 1,
  48. "result": {
  49. "tools": [
  50. {
  51. "description": "Vibrates device by `id`, selecting `strength` and optional `motor`",
  52. "inputSchema": {
  53. "type": "object",
  54. "properties": {
  55. "id": {
  56. "description": "Device ID to query, sourced from `/devices`",
  57. "pattern": "^[0-9]*$",
  58. "type": "number"
  59. },
  60. "motor": {
  61. "description": "Motor number to vibrate, defaults to 0",
  62. "pattern": "^[0-9]*$",
  63. "type": "number"
  64. },
  65. "strength": {
  66. "description": "Strength from 0.0 to 1.0, with 0.0 being off and 1.0 being full",
  67. "pattern": "^(0(\\.\\d+)?|1(\\.0+)?)$",
  68. "type": "number"
  69. }
  70. },
  71. "required": [
  72. "id",
  73. "strength"
  74. ]
  75. },
  76. "name": "device_vibrate"
  77. }
  78. ]
  79. }
  80. }
  81. ```
  82. </details>
  83. ## Current State
  84. I started working on this on 2025-04-01, April Fool's Day, after having created another experimental MCP service, [`dbn-go` for financial market data](https://github.com/NimbleMarkets/dbn-go/blob/main/cmd/dbn-go-mcp/README.md), the day prior. So it is fresh meat and was intended as a quick, fun educational project.
  85. While it does work, I found the underlying [`go-buttplug` library](https://github.com/diamondburned/go-buttplug) to be unstable in connection handling. I could ask Claude for my devices, but my specific device wouldn't vibrate even just with just Intiface Central -- it was like in read-only mode! I also wish I had a virtual buttplug.io device for testing, rather than relying on a physical device.
  86. So, it has not truly been tested "end-to-end" :wink:
  87. I will dig more into the `go-buttplug` library and see why connections are unstable. I also need to understand the MCP protocol current state of MCP hosts -- it seems they focus on Tools rather than Resources and Resoure Templates.
  88. ## Installing the binary
  89. Binaries for multiple platforms are [released on GitHub](https://github.com/conacademy/buttplug-mcp/releases) through [GitHub Actions](https://github.com/conacademy/buttplug-mcp/actions).
  90. You can also install for various platforms with [Homebrew](https://brew.sh) from [`conacademy/homebrew-tap`](https://github.com/conacademy/homebrew-tap):
  91. ```
  92. brew tap conacademy/homebrew-tap
  93. brew install conacademy/tap/buttplug-mcp
  94. ```
  95. ## Usage
  96. Download the [Intiface Central](https://intiface.com/central/) hub application to manage your devices. Start it and note the server port (default seems to be `12345`).
  97. To use this the `buttplug-mcp` MCP server, you must configure your host program to use it. We will illustrate with [Claude Desktop](https://claude.ai/download). We must find the `buttplug-mcp` program on our system; the example below shows where `buttplug-mcp` is installed with MacOS Homebrew (perhaps build your own and point at that).
  98. The following [configuration JSON](./claude_desktop_config.json) sets this up:
  99. ```json
  100. {
  101. "mcpServers": {
  102. "buttplug": {
  103. "command": "/opt/homebrew/bin/buttplug-mcp",
  104. "args": [
  105. "--ws-port", "12345"
  106. ]
  107. }
  108. }
  109. }
  110. ```
  111. Using Claude Desktop, you can follow [their configuration tutorial](https://modelcontextprotocol.io/quickstart/user) but substitute the configuration above. With that in place, you can ask Claude question and it will use the `buttplug-mcp` server. Here's example conversations:
  112. Perhaps you can use the [HomeAssistant MCP](https://www.home-assistant.io/integrations/mcp_server/) integration to turn the lights down low...
  113. ### Ollama and `mcphost`
  114. For local inferencing, there are MCP hosts that support [Ollama](https://ollama.com/download). You can use any [Ollama LLM that supports "Tools"](https://ollama.com/search?c=tools). We experimented with [`mcphost`](https://github.com/mark3labs/mcphost), authored by the developer of the [`mcp-go` library](https://github.com/mark3labs/mcp-go) that peformed the heavy lifting for us.
  115. Here's how to install and run with it with the configuration above, stored in `mcp.json`:
  116. ```
  117. $ go install github.com/mark3labs/mcphost@latest
  118. $ mcphost -m ollama:llama3.3 --config mcp.json
  119. ...chat away...
  120. ```
  121. It seems that only "Tools" are supported and not "Resources", so I couldn't enumerate and introspect my device. But I had this Tool interaction (but as noted [above](#current-state), my device didn't actually vibrate):
  122. ```
  123. $ mcphost -m ollama:phi4-mini --config mcp.json
  124. 2025/04/02 09:25:05 INFO Model loaded provider=ollama model=phi4-mini
  125. 2025/04/02 09:25:05 INFO Initializing server... name=buttplug
  126. 2025/04/02 09:25:05 INFO Server connected name=buttplug
  127. 2025/04/02 09:25:05 INFO Tools loaded server=buttplug count=1
  128. 2025/04/02 09:28:31 INFO Model loaded provider=ollama model=phi4-mini
  129. 2025/04/02 09:28:31 INFO Initializing server... name=buttplug
  130. 2025/04/02 09:28:31 INFO Server connected name=buttplug
  131. 2025/04/02 09:28:31 INFO Tools loaded server=buttplug count=1
  132. /servers
  133. # buttplug
  134. Command /opt/homebrew/bin/buttplug-mcp
  135. Arguments --ws-port 12345
  136. /tools
  137. • buttplug
  138. • device_vibrate
  139. • Vibrates device by ID, selecting strength and optional motor
  140. You: buttplug device_vibrate id 0 at strength 1
  141. Assistant:
  142. <|tool_call|>[start_processing]
  143. [{"type":"function","function":{"name":"buttplug__device_vibrate","description":"Vibrates device by ID, selecting strength and optional
  144. motor","parameters":{"id":0,"strength":1}}]
  145. {}
  146. {"status":"success","message":"Device with id 0 is vibrating at full strength."}
  147. ```
  148. ## Building
  149. Building is performed with [task](https://taskfile.dev/), with the binary available in `bin/buttplug-mcp`.
  150. ```
  151. $ task
  152. task: [tidy] go mod tidy
  153. task: [build] go build -o bin/buttplug-mcp cmd/buttplug-mcp/main.go
  154. ```
  155. Useful testing tools:
  156. * `task stdio-schema | jq` -- prints out JSON schemas
  157. * `npx @modelcontextprotocol/inspector node build/index.js` -- [MCP Inspector Web GUI](https://github.com/modelcontextprotocol/inspector)
  158. ## CLI Arguments
  159. ```
  160. R buttplug-mcp --help
  161. usage: buttplug-mcp [opts]
  162. -h, --help Show help
  163. -l, --log-file string Log file destination (or MCP_LOG_FILE envvar). Default is stderr
  164. -j, --log-json Log in JSON (default is plaintext)
  165. --sse Use SSE Transport (default is STDIO transport)
  166. --sse-host string host:port to listen to SSE connections
  167. -v, --verbose Verbose logging
  168. --ws-port int port to connect to the Buttplug Websocket server
  169. ```
  170. ## Contribution and Conduct
  171. As with all ConAcademy projects, pull requests are welcome. Or fork it. You do you.
  172. Either way, obey our [Code of Conduct](./CODE_OF_CONDUCT.md). Be shady, but don't be a jerk.
  173. ## Credits and License
  174. Thanks for `go-buttplug` for the [Golang Buttplug.io library](https://github.com/diamondburned/go-buttplug) and its [`buttplughttp` example](https://github.com/diamondburned/go-buttplug/tree/plug/cmd/buttplughttp), and `go-mcp` for the [Golang Model Context Protocol library](https://github.com/mark3labs/mcp-go).
  175. Copyright (c) 2025 Neomantra BV. Authored by Evan Wies for [ConAcademy](https://github.com/conacademy).
  176. Released under the [MIT License](https://en.wikipedia.org/wiki/MIT_License), see [LICENSE.txt](./LICENSE.txt).

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.