{"id":26251148,"url":"https://github.com/oleander/home-assistant-mcp-server","last_synced_at":"2026-03-07T04:01:41.761Z","repository":{"id":280985517,"uuid":"943829809","full_name":"oleander/home-assistant-mcp-server","owner":"oleander","description":"home-assistant-mcp-server","archived":false,"fork":false,"pushed_at":"2025-12-01T19:07:18.000Z","size":1265,"stargazers_count":3,"open_issues_count":3,"forks_count":3,"subscribers_count":2,"default_branch":"main","last_synced_at":"2026-02-17T05:09:05.561Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/oleander.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2025-03-06T10:35:48.000Z","updated_at":"2025-12-24T11:38:14.000Z","dependencies_parsed_at":"2025-04-14T05:46:32.741Z","dependency_job_id":"acccb86d-0d43-4bcb-8899-fcf42016e610","html_url":"https://github.com/oleander/home-assistant-mcp-server","commit_stats":null,"previous_names":["oleander/home-assistant-mcp-server"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/oleander/home-assistant-mcp-server","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/oleander%2Fhome-assistant-mcp-server","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/oleander%2Fhome-assistant-mcp-server/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/oleander%2Fhome-assistant-mcp-server/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/oleander%2Fhome-assistant-mcp-server/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/oleander","download_url":"https://codeload.github.com/oleander/home-assistant-mcp-server/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/oleander%2Fhome-assistant-mcp-server/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":30207390,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-03-07T03:24:23.086Z","status":"ssl_error","status_checked_at":"2026-03-07T03:23:11.444Z","response_time":53,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.6:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2025-03-13T16:51:54.055Z","updated_at":"2026-03-07T04:01:41.737Z","avatar_url":"https://github.com/oleander.png","language":"TypeScript","funding_links":[],"categories":["Other Tools and Integrations","🌐 Web Development","Smart Home \u0026 IoT Mcp Servers"],"sub_categories":["How to Submit"],"readme":"# Home Assistant MCP Server\n\nA [Model Context Protocol (MCP)](https://modelcontextprotocol.io/) server for integrating with [Home Assistant](https://www.home-assistant.io/), allowing LLMs to control and query your smart home.\n\n## Features\n\n- Query and control Home Assistant entities via natural language\n- Works with any MCP-compatible client (like Claude Desktop)\n- Provides tools for state management, service calls, history, and more\n- Secure authentication using Home Assistant long-lived access tokens\n- Multiple transport options (stdio for local processes, SSE for remote clients)\n- Demo mode with mock data for testing and demonstration when Home Assistant is not available\n\n## Installation\n\n```bash\n# Install globally using bun\nbun install -g home-assistant-mcp-server\n\n# Or install from source\ngit clone https://github.com/oleander/home-assistant-mcp-server.git\ncd home-assistant-mcp-server\nbun install\nbun run build\nbun link\n```\n\n## Configuration\n\nCreate a `.env` file in your current directory with the following variables:\n\n```\n# Required configurations\nHASS_URL=http://your-home-assistant:8123  # URL to your Home Assistant instance\nHASS_TOKEN=your_long_lived_access_token   # Long-lived access token for authentication\n\n# Optional configurations\nPORT=3000                # Port for the HTTP server (default: 3000)\nHASS_MOCK=false          # Enable mock data mode when Home Assistant is unavailable (default: false)\n```\n\n### Environment Variables\n\n| Variable     | Required | Default | Description                                                                                |\n| ------------ | -------- | ------- | ------------------------------------------------------------------------------------------ |\n| `HASS_URL`   | Yes      | -       | URL to your Home Assistant instance (e.g., http://homeassistant.local:8123)                |\n| `HASS_TOKEN` | Yes      | -       | Long-lived access token for authenticating with Home Assistant                             |\n| `PORT`       | No       | 3000    | Port number for the HTTP server when using HTTP/SSE transport                              |\n| `HASS_MOCK`  | No       | false   | When set to \"true\", enables mock data mode for testing without a Home Assistant connection |\n\nTo get a long-lived access token:\n\n1. Log in to your Home Assistant instance\n2. Click on your profile (bottom left)\n3. Scroll down to \"Long-Lived Access Tokens\"\n4. Create a new token with a descriptive name\n5. Copy the token value (you won't see it again)\n\n## Usage\n\n### Running as a standalone server\n\n```bash\n# Standard mode (requires a running Home Assistant instance)\nhome-assistant-mcp-server                # Start with HTTP/SSE transport\nhome-assistant-mcp-server --stdio        # Start with stdio transport for direct process communication\n\n# Demo mode (with mock data when Home Assistant is unavailable)\nhome-assistant-mcp-server --mock         # Start with HTTP/SSE transport and mock data\nhome-assistant-mcp-server --stdio --mock # Start with stdio transport and mock data\n```\n\n### Integration with Claude Desktop\n\nTo use with Claude Desktop:\n\n1. Edit your Claude Desktop config file:\n\n   - macOS: `~/Library/Application Support/Claude/claude_desktop_config.json`\n   - Windows: `%APPDATA%\\Claude\\claude_desktop_config.json`\n\n2. Add the server configuration:\n\n```json\n{\n  \"mcpServers\": {\n    \"homeassistant\": {\n      \"command\": \"home-assistant-mcp-server\"\n      \"env\": {\n        \"HASS_URL\": \"http://your-home-assistant:8123\",\n        \"HASS_TOKEN\": \"your_token_here\",\n        \"HASS_MOCK\": \"true\"\n      }\n    }\n  }\n}\n```\n\nIf you have Home Assistant running, simply remove the `--mock` flag and set `HASS_MOCK` to `false`.\n\n3. Restart Claude Desktop\n\n## Available Tools\n\nThe server exposes several tools for interacting with Home Assistant:\n\n- `states` - Query entity states\n- `lights` - List lights\n- `light` - Control a light\n- `service` - Call Home Assistant services\n- `history` - Retrieve historical entity data\n- `services` - List available services\n- `config` - Get Home Assistant configuration\n- `domains` - List available domains\n- `error_log` - Get Home Assistant error log\n- `devices` - Get all devices in Home Assistant\n\nFor detailed usage examples, see [docs/hass-mcp.md](docs/hass-mcp.md).\n\n## Security\n\nThis server requires a Home Assistant access token with full access. Consider these security recommendations:\n\n- Only run the server on trusted networks\n- Use HTTPS if exposing the server remotely\n- Keep your `.env` file secure and don't commit it to source control\n- Consider using a token with limited permissions when possible\n\n## License\n\nThis project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Foleander%2Fhome-assistant-mcp-server","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Foleander%2Fhome-assistant-mcp-server","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Foleander%2Fhome-assistant-mcp-server/lists"}