Profpatsch/users/Profpatsch/varlink-mcp-bridge

View full contents ↓

A bridge that exposes Varlink services as MCP (Model Context Protocol) tools for Claude Code.

Install:

nix profile install https://sources.profpatsch.de/Profpatsch.tar.gz#varlink-mcp-bridge

Configure (.mcp.json in your project):

{
  "mcpServers": {
    "my-service": {
      "command": "varlink-mcp-bridge",
      "args": [
        "--varlink-address=unix:/run/user/1000/my.service.Socket",
        "--interface=my.service.Interface"
      ]
    }
  }
}

Restart Claude Code to load the MCP server.

See man varlink-mcp-bridge for comprehensive documentation including:

Or view the manpage directly:

man ./varlink-mcp-bridge.1

  1. Connects to your Varlink service
  2. Introspects the interface definition
  3. Exposes each method as an MCP tool with auto-generated JSON Schema
  4. Translates tool calls ↔ Varlink method invocations
  5. Preserves documentation from Varlink interface comments

Example: A Varlink method GetLastPosition() -> (path: string, line: int) becomes an MCP tool GetLastPosition that Claude can invoke.

With Nix:

nix-build ~/kot/Profpatsch -A users.Profpatsch.varlink-mcp-bridge

With Go:

go build

varlink-mcp-bridge(1)

varlink-mcp-bridge - expose Varlink services as MCP (Model Context Protocol) tools

varlink-mcp-bridge --varlink-address address --interface name [--debug]

varlink-mcp-bridge connects to a Varlink service, introspects its interface definition, and exposes all methods as MCP tools over stdio. This enables Claude Code to invoke Varlink service methods directly as AI-available tools with automatic type translation and documentation.

The bridge handles the complete protocol translation:

The following options are available:

--varlink-address address

Varlink service address to connect to. Supports Unix domain sockets (unix:/path/to/socket) or TCP addresses (tcp:host:port). Required.

--interface name

Varlink interface name to expose via MCP. Must match an interface provided by the service at the given address. The interface name follows reverse-DNS notation (e.g., de.profpatsch.ClaudeLastPosition). Required.

--debug

Enable verbose debug logging to stderr. Shows all JSON-RPC messages, Varlink calls, and internal state transitions. Useful for troubleshooting bridge configuration or service communication issues.

varlink-mcp-bridge is designed to be invoked by MCP clients (such as Claude Code) via the stdio transport. It communicates using JSON-RPC 2.0 protocol and follows the MCP specification.

Create or edit .mcp.json in your project directory:

{
  "mcpServers": {
    "my-service": {
      "command": "/path/to/varlink-mcp-bridge",
      "args": [
        "--varlink-address=unix:/run/user/1000/my.service.Socket",
        "--interface=my.service.Interface"
      ]
    }
  }
}

Multiple Varlink services can be exposed by adding additional entries to mcpServers. Each bridge instance connects to one interface.

MCP tool names are taken directly from Varlink method names with no transformation. For example:

Interface: de.profpatsch.DisplayBrightness
Method: SetBrightnessAllMonitors
Tool name: SetBrightnessAllMonitors

This keeps tool names consistent with the original Varlink interface and makes debugging easier since tool names match method names exactly

Tool descriptions are extracted directly from Varlink interface documentation comments (using # syntax). This makes MCP tools self-documenting and discoverable in Claude Code's tool browser.

varlink-mcp-bridge performs the following operations on startup:

  1. Connects to the Varlink service at the specified address

  2. Calls org.varlink.service.GetInterfaceDescription to retrieve the interface definition

  3. Parses the Varlink IDL using the official IDL parser

  4. Translates each method signature into MCP tool schema with JSON Schema types

  5. Enters stdio loop, processing MCP JSON-RPC requests

  6. For each tools/call request, invokes the corresponding Varlink method

  7. Returns Varlink response data formatted as MCP tool result

Connections to the Varlink service are persistent and reused across multiple tool invocations for efficiency.

Varlink types are translated to JSON Schema as follows:

bool

boolean

int, float

integer, number

string

string

[]T

array with items type T

?T

Optional type (not in required list)

[string]T

object with additionalProperties of type T

(field: T, ...)

object with typed properties

$ varlink-mcp-bridge \
    --varlink-address=unix:/run/user/1000/de.Profpatsch.ClaudeLastPosition \
    --interface=de.profpatsch.ClaudeLastPosition

This exposes methods like GetLastPosition and SetLastPosition as MCP tools that Claude can invoke.

$ varlink-mcp-bridge \
    --varlink-address=unix:/run/user/1000/de.Profpatsch.DisplayBrightness \
    --interface=de.profpatsch.DisplayBrightness


$ varlink-mcp-bridge \
    --varlink-address=unix:/run/user/1000/my.Service \
    --interface=my.Service \
    --debug 2>debug.log

Logs all protocol messages to debug.log for troubleshooting.

Build and install using Nix flakes:

$ nix profile install git+https://codeberg.org/Profpatsch/Profpatsch?ref=canon#varlink-mcp-bridge

This installs varlink-mcp-bridge and the man page to your Nix profile.

varlink-mcp-bridge returns MCP error responses in the following cases:

Parse Error (-32700)

Invalid JSON received from MCP client

Invalid Request (-32600)

Malformed JSON-RPC request (missing required fields, non-monotonic ID)

Method Not Found (-32601)

Unknown MCP method (not initialize, tools/list, or tools/call)

Invalid Params (-32602)

Unknown tool name or invalid tool arguments

Internal Error (-32603)

Varlink call failed (connection error, unknown method, service error)

Error messages include detailed context to aid debugging, such as the actual Varlink error returned by the service.

.mcp.json

MCP server configuration file specifying which Varlink services to expose

/run/user/<uid>/*‌

Common location for user-specific Varlink service Unix sockets

The varlink-mcp-bridge utility exits 0 on success, and >0 if an error occurs.

The bridge runs indefinitely as an MCP server until the client closes stdin or sends a termination signal.

varlink(7)

Varlink Protocol: https://varlink.org

Model Context Protocol: https://modelcontextprotocol.io

Claude Code Documentation: https://docs.claude.com/claude-code

Profpatsch

varlink-mcp-bridge was created with
Claude Code.