homebridge-mcp-server

lucaspbastos/homebridge-mcp-server

3.1

If you are the rightful owner of homebridge-mcp-server and would like to certify it and/or have it hosted online, please leave a comment on the right or send an email to dayong@mcphub.com.

This is an experimental MCP server designed to interface with a Homebridge installation, facilitating communication and control over smart home devices.

Homebridge MCP Server

Experimental MCP server for interfacing with a Homebridge installation.

Prerequisites

  • Node.js 24.x (specified in .nvmrc)
  • npm (comes with Node.js)

Installation

Install Node.js

Using nvm (recommended):

nvm install
nvm use

Or manually install Node.js 24.x from nodejs.org.

Install Dependencies

npm install

Development

Build

Compiles TypeScript to the build/ directory:

npm run build

Run

Execute the built server:

npm start

Watch Mode

Automatically rebuild on file changes:

npm run dev

Linting

Run ESLint checks:

npm run lint

Testing

Run test suite:

npm test

Docker

Build Docker Image

Local testing:

./scripts/test-docker-build.sh

This builds a Docker image tagged as homebridge-mcp-server:local.

Run Docker Container

docker run --rm homebridge-mcp-server:local

Local Testing Scripts

The scripts/ directory contains utilities for testing CI/CD workflows locally:

  • test-ci.sh - Simulates CI quality checks (lint + test + build)
  • test-docker-build.sh - Builds Docker image locally
  • test-publish.sh - Simulates release workflow with version bumping

See scripts/README.md for detailed usage instructions.

Installation as CLI Tool

Once published to npm, install globally:

npm install -g homebridge-mcp-server

Or run directly with npx:

npx homebridge-mcp-server

CI/CD Workflows

Continuous Integration

Runs on feature branches and pull requests:

  • Quality checks (lint + test)
  • Build validation
  • Automated via .github/workflows/ci.yaml

Release Workflow

Manual or tag-triggered releases:

  • Version calculation and package updates
  • Publishes to npm (with approval)
  • Builds and publishes Docker images to GHCR and Docker Hub (with approval)
  • Creates GitHub releases
  • Automated via .github/workflows/release.yaml

Project Structure

.
├── src/                  # TypeScript source files
├── build/                # Compiled JavaScript (git-ignored)
├── scripts/              # Local testing utilities
├── .github/workflows/    # CI/CD workflows
├── containers/           # Docker development environment
└── Dockerfile            # Multi-stage Alpine build

License

ISC