schema_resources.json

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

schema_tools.json

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "tools": [
      {
        "description": "Vibrates device by `id`, selecting `strength` and optional `motor`",
        "inputSchema": {
          "type": "object",
          "properties": {
            "id": {
              "description": "Device ID to query, sourced from `/devices`",
              "pattern": "^[0-9]*$",
              "type": "number"
            },
            "motor": {
              "description": "Motor number to vibrate, defaults to 0",
              "pattern": "^[0-9]*$",
              "type": "number"
            },
            "strength": {
              "description": "Strength from 0.0 to 1.0, with 0.0 being off and 1.0 being full",
              "pattern": "^(0(\\.\\d+)?|1(\\.0+)?)$",
              "type": "number"
            }
          },
          "required": [
            "id",
            "strength"
          ]
        },
        "name": "device_vibrate"
      }
    ]
  }
}

Current State

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, the day prior. So it is fresh meat and was intended as a quick, fun educational project.

While it does work, I found the underlying go-buttplug library 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.

So, it has not truly been tested "end-to-end" :wink:

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.

Installing the binary

Binaries for multiple platforms are released on GitHub through GitHub Actions.

You can also install for various platforms with Homebrew from conacademy/homebrew-tap:

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

Usage

Download the Intiface Central hub application to manage your devices. Start it and note the server port (default seems to be 12345).

To use this the buttplug-mcp MCP server, you must configure your host program to use it. We will illustrate with Claude Desktop. 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).

The following configuration JSON sets this up:

{
  "mcpServers": {
    "buttplug": {
      "command": "/opt/homebrew/bin/buttplug-mcp",
      "args": [
        "--ws-port", "12345"
      ]
    }
  }
}

Using Claude Desktop, you can follow their configuration tutorial 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:

Perhaps you can use the HomeAssistant MCP integration to turn the lights down low...

Ollama and mcphost

For local inferencing, there are MCP hosts that support Ollama. You can use any Ollama LLM that supports "Tools". We experimented with mcphost, authored by the developer of the mcp-go library that peformed the heavy lifting for us.

Here's how to install and run with it with the configuration above, stored in mcp.json:

$ go install github.com/mark3labs/mcphost@latest
$ mcphost -m ollama:llama3.3 --config mcp.json
...chat away...

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, my device didn't actually vibrate):

$ mcphost -m ollama:phi4-mini --config mcp.json
2025/04/02 09:25:05 INFO Model loaded provider=ollama model=phi4-mini
2025/04/02 09:25:05 INFO Initializing server... name=buttplug
2025/04/02 09:25:05 INFO Server connected name=buttplug
2025/04/02 09:25:05 INFO Tools loaded server=buttplug count=1
2025/04/02 09:28:31 INFO Model loaded provider=ollama model=phi4-mini
2025/04/02 09:28:31 INFO Initializing server... name=buttplug
2025/04/02 09:28:31 INFO Server connected name=buttplug
2025/04/02 09:28:31 INFO Tools loaded server=buttplug count=1
/servers
      # buttplug
      Command /opt/homebrew/bin/buttplug-mcp
      Arguments --ws-port 12345

/tools
  • buttplug
    • device_vibrate
      • Vibrates device by ID, selecting strength and optional motor

  You: buttplug device_vibrate id 0 at strength 1

  Assistant:
  <|tool_call|>[start_processing]

  [{"type":"function","function":{"name":"buttplug__device_vibrate","description":"Vibrates device by ID, selecting strength and optional
  motor","parameters":{"id":0,"strength":1}}]

  {}

  {"status":"success","message":"Device with id 0 is vibrating at full strength."}

Building

Building is performed with task, with the binary available in bin/buttplug-mcp.

$ task
task: [tidy] go mod tidy
task: [build] go build -o bin/buttplug-mcp cmd/buttplug-mcp/main.go

Useful testing tools:

• task stdio-schema | jq -- prints out JSON schemas
• npx @modelcontextprotocol/inspector node build/index.js -- MCP Inspector Web GUI

CLI Arguments

R buttplug-mcp --help
usage: buttplug-mcp [opts]

  -h, --help              Show help
  -l, --log-file string   Log file destination (or MCP_LOG_FILE envvar). Default is stderr
  -j, --log-json          Log in JSON (default is plaintext)
      --sse               Use SSE Transport (default is STDIO transport)
      --sse-host string   host:port to listen to SSE connections
  -v, --verbose           Verbose logging
      --ws-port int       port to connect to the Buttplug Websocket server

Contribution and Conduct

As with all ConAcademy projects, pull requests are welcome. Or fork it. You do you.

Either way, obey our Code of Conduct. Be shady, but don't be a jerk.

Credits and License

Thanks for go-buttplug for the Golang Buttplug.io library and its buttplughttp example, and go-mcp for the Golang Model Context Protocol library.

Copyright (c) 2025 Neomantra BV. Authored by Evan Wies for ConAcademy.

Released under the MIT License, see LICENSE.txt.