elvatis-mcp

MCP server for OpenClaw -- expose your smart home, memory, cron automation, and AI sub-agent orchestration to Claude Desktop, Cursor, Windsurf, and any MCP-compatible AI client.

What is this?

elvatis-mcp connects Claude (or any MCP client) to your infrastructure:

Smart home control via Home Assistant (lights, thermostats, vacuum, sensors)
Memory system with daily logs stored on your OpenClaw server
Cron job management and triggering
Multi-LLM orchestration through 5 AI backends: Claude, OpenClaw, Google Gemini, OpenAI Codex, and local LLMs
Smart prompt splitting that analyzes complex requests, routes sub-tasks to the right AI, and executes the plan with rate limiting

The key idea: Claude is the orchestrator, but it can delegate specialized work to other AI models. Coding tasks go to Codex. Research goes to Gemini. Simple formatting goes to your local LLM (free, private). Trading and automation go to OpenClaw. prompt_split figures out the routing automatically, and prompt_split_execute runs the plan with rate limiting on cloud agents.

What is MCP?

Model Context Protocol is an open standard by Anthropic that lets AI clients connect to external tool servers. Once configured, Claude can directly call your tools without copy-pasting.

Multi-LLM Architecture

                         You (Claude Desktop / Code / Cursor)
                                      |
                              MCP Protocol (stdio/HTTP)
                                      |
                              elvatis-mcp server
                                      |
              +--------+--------+--------+--------+--------+--------+
              |        |        |        |        |        |        |
          Claude  OpenClaw  Gemini   Codex   Local   llama   Home
          (CLI)   (SSH)     (CLI)    (CLI)   LLM    .cpp    Asst.
              |        |        |        |    (HTTP)  (proc)  (REST)
          Reason  Plugins  1M ctx  Coding    |        |        |
          Write   Trading  Multi-  Files   LM Stu  Turbo-  Lights
          Review  Auto.    modal   Debug   Ollama  Quant   Climate
                  Notify   Rsch    Shell   (free!) cache   Vacuum

Sub-Agent Comparison

Tool	Backend	Transport	Auth	Best for	Cost
`claude_run`	Claude (Anthropic)	Local CLI	Claude Code login	Complex reasoning, writing, code review. For non-Claude MCP clients.	API usage
`openclaw_run`	OpenClaw (plugins)	SSH	SSH key	Trading, automations, multi-step workflows	Self-hosted
`gemini_run`	Google Gemini	Local CLI	Google login	Long context (1M tokens), multimodal, research	API usage
`codex_run`	OpenAI Codex	Local CLI	OpenAI login	Coding, debugging, file editing, shell scripts	API usage
`local_llm_run`	LM Studio / Ollama / llama.cpp	HTTP	None	Classification, formatting, extraction, rewriting	Free

Smart Prompt Splitting

The prompt_split tool analyzes complex prompts and breaks them into sub-tasks:

User: "Search my memory for TurboQuant notes, summarize with Gemini,
       reformat as JSON locally, then save a summary to memory"

prompt_split returns:
  t1: openclaw_memory_search  -- "Search memory for TurboQuant"        (parallel)
  t3: local_llm_run           -- "Reformat raw notes as clean JSON"    (parallel)
  t2: gemini_run              -- "Summarize the key findings"          (after t1)
  t4: openclaw_memory_write   -- "Save summary to today's log"        (after t2, t3)

Use prompt_split_execute to run the plan automatically, or let Claude execute it step by step. Tasks run in dependency order with parallel groups executed concurrently. Three analysis strategies:

Strategy	Speed	Quality	Uses
`heuristic`	Instant	Good for clear prompts	Keyword matching, no LLM call
`local`	5-30s	Better reasoning	Your local LLM analyzes the prompt
`gemini`	5-15s	Best quality	Gemini-flash analyzes the prompt
`auto` (default)	Varies	Best available	Short-circuits simple prompts, then tries gemini -> local -> heuristic

Available Tools (34 total)

Home Assistant (7 tools)

Tool	Description
`home_get_state`	Read any Home Assistant entity state
`home_light`	Control lights: on/off/toggle, brightness, color temperature, RGB
`home_climate`	Control Tado thermostats: temperature, HVAC mode
`home_scene`	Activate Hue scenes by room
`home_vacuum`	Control Roborock vacuum: start, stop, dock, status
`home_sensors`	Read all temperature, humidity, and CO2 sensors
`home_automation`	List, trigger, enable, or disable HA automations

Memory (3 tools)

Tool	Description
`openclaw_memory_write`	Write a note to today's daily log
`openclaw_memory_read_today`	Read today's memory log
`openclaw_memory_search`	Search memory files across the last N days

Cron Automation (7 tools)

Tool	Description
`openclaw_cron_list`	List all scheduled OpenClaw cron jobs
`openclaw_cron_run`	Trigger a cron job immediately by ID
`openclaw_cron_status`	Get scheduler status and recent run history
`openclaw_cron_create`	Create a new cron job (cron expression, interval, or one-shot)
`openclaw_cron_edit`	Edit an existing cron job (name, message, schedule, model)
`openclaw_cron_delete`	Delete a cron job by ID
`openclaw_cron_history`	Show recent execution history for a cron job

OpenClaw Agent (4 tools)

Tool	Description
`openclaw_run`	Send a prompt to the OpenClaw AI agent (all plugins available)
`openclaw_status`	Check if the OpenClaw daemon is running
`openclaw_plugins`	List all installed plugins
`openclaw_notify`	Send a notification via WhatsApp, Telegram, or last-used channel

AI Sub-Agents (5 tools)

Tool	Description
`claude_run`	Send a prompt to Claude via the local CLI. For non-Claude MCP clients (Cursor, Windsurf).
`gemini_run`	Send a prompt to Google Gemini via the local CLI. 1M token context.
`codex_run`	Send a coding task to OpenAI Codex via the local CLI.
`local_llm_run`	Send a prompt to a local LLM (LM Studio, Ollama, llama.cpp). Free, private. Supports streaming.
`llama_server`	Start/stop/configure a llama.cpp server with TurboQuant cache support.

System Management (4 tools)

Tool	Description
`system_status`	Health check all services at once with latency (HA, SSH, LLM, CLIs)
`local_llm_models`	List, load, or unload models on LM Studio / Ollama
`openclaw_logs`	View gateway, agent, or system logs from the OpenClaw server
`file_transfer`	Upload, download, or list files on the OpenClaw server via SSH

Routing and Orchestration (3 tools)

Tool	Description
`mcp_help`	Show routing guide. Pass a task to get a specific tool recommendation.
`prompt_split`	Analyze a complex prompt, split into sub-tasks with agent assignments.
`prompt_split_execute`	Execute a split plan: dispatch subtasks to agents in dependency order with rate limiting.

Dashboard

Endpoint	Description
`http://localhost:3334/status`	Auto-refreshing HTML dashboard (service health, loaded models)
`http://localhost:3334/api/status`	JSON API for programmatic status checks

Test Results

All tests run against live services (LM Studio with Deepseek R1 Qwen3 8B, OpenClaw server via SSH).

  elvatis-mcp integration tests

  Local LLM (local_llm_run)

        Model: deepseek/deepseek-r1-0528-qwen3-8b
        Response: "negative"
        Tokens: 401 (prompt: 39, completion: 362)
  PASS  local_llm_run: simple classification (21000ms)
        Extracted: {"name":"John Smith","age":34}
  PASS  local_llm_run: JSON extraction (24879ms)
        Error: Could not connect to local LLM at http://localhost:19999/v1/chat/completions
  PASS  local_llm_run: connection error handling (4ms)

  Prompt Splitter (prompt_split)

        Strategy: heuristic
        Agent: codex_run
        Summary: Fix the authentication bug in the login handler
  PASS  prompt_split: single-domain coding prompt routes to codex (1ms)
        Strategy: heuristic
        Subtasks: 3
          t1: codex_run -- "Refactor the auth module"
          t2: openclaw_run -- "check my portfolio performance and"
          t3: home_light -- "turn on the living room lights"
        Parallel groups: [["t1","t3"],["t2"]]
        Estimated time: 90s
  PASS  prompt_split: heuristic multi-agent splitting (0ms)
        Subtasks: 4, Agents: openclaw_memory_write, gemini_run, local_llm_run
        Parallel groups: [["t1","t3","t4"],["t2"]]
  PASS  prompt_split: cross-domain with dependencies (1ms)
        Strategy: local->heuristic (fallback)
        Subtasks: 1
  PASS  prompt_split: local LLM strategy (with fallback) (60007ms)

  Routing Guide (mcp_help)

        Guide length: 2418 chars
  PASS  mcp_help: returns guide without task (0ms)
        Recommendation: local_llm_run (formatting task)
  PASS  mcp_help: routes formatting task to local_llm_run (0ms)
        Recommendation: codex_run (coding task)
  PASS  mcp_help: routes coding task to codex_run (0ms)

  Memory Search via SSH (openclaw_memory_search)

        Query: "trading", Results: 5
  PASS  openclaw_memory_search: finds existing notes (208ms)

  -----------------------------------------------------------
  11 passed, 0 failed, 0 skipped
  -----------------------------------------------------------

Run the tests yourself:

npx tsx tests/integration.test.ts

Prerequisites: .env configured, local LLM server running, OpenClaw server reachable via SSH.

Benchmarks

See BENCHMARKS.md for the full benchmark suite, methodology, and community contribution guide.

Reference Hardware

Component	Spec
CPU	AMD Threadripper 3960X (24 cores / 48 threads)
GPU	AMD Radeon RX 9070 XT Elite (16 GB GDDR6)
RAM	128 GB DDR4
OS	Windows 11 Pro
Runtime	LM Studio + Vulkan (`llama.cpp-win-x86_64-vulkan-avx2@2.8.0`)

Local LLM Inference (LM Studio, Vulkan GPU, `--gpu max`)

Median of 3 runs, max_tokens=512. Tasks: classify (1-word sentiment), extract (JSON), reason (arithmetic), code (Python function). Vulkan is the recommended runtime for AMD RX 9070 XT (wins 4 of 5 models over ROCm).

Model	Params	classify	extract	reason	code	avg tok/s
Phi 4 Mini Reasoning	3B	2.6s	1.9s	4.7s	4.8s	106
Deepseek R1 0528 Qwen3	8B	3.0s	6.5s	7.2s	7.4s	70
Qwen 3.5 9B	9B	6.2s	4.0s	8.4s	7.2s	48
Phi 4 Reasoning Plus	15B	0.4s	9.7s	3.5s	9.9s	40
GPT-OSS 20B	20B	0.6s	0.6s	0.6s	1.9s	63

GPU speedup vs CPU (Deepseek R1 8B, Vulkan): classify 7.2x faster, extract 3.8x faster.

Sub-Agent Comparison (same task, different backends)

Agent	Backend	Avg Latency	Cost	Notes
local_llm_run	GPT-OSS 20B (Vulkan GPU)	1.0s	Free	4x faster than Codex, 6x faster than Claude
codex_run	OpenAI Codex CLI	4.1s	Pay-per-use	Best for coding tasks
claude_run	Claude Sonnet 4.6	6.3s	Pay-per-use	Best for complex reasoning
gemini_run	Gemini 2.5 Flash	34.0s	Free tier	CLI startup overhead, best for long context

Service Latency (system_status)

Service	Latency	Notes
Home Assistant (REST API)	48-84 ms	Local network, direct HTTP
OpenClaw SSH	273-299 ms	LAN SSH + command execution
Local LLM (model list)	19-38 ms	LM Studio localhost API
Claude CLI (version check)	472-478 ms	CLI startup overhead
Codex CLI (version check)	131-136 ms	CLI startup overhead
Gemini CLI (version check)	4,700-4,900 ms	CLI startup + auth check

prompt_split Accuracy (heuristic strategy)

Metric	Result
Pass rate	10/10 (100%)
Task count accuracy	10/10 (100%)
Avg agent match	100%
Latency	<1ms (no LLM call)

Improvements in v0.8.0+: word boundary regex matching, comma-clause splitting for multi-agent prompts, per-tool routing rules, openclaw_notify routing. See BENCHMARKS.md for the full test corpus.

Want to contribute benchmarks from your hardware? See BENCHMARKS.md.

Requirements

Node.js 18 or later
OpenSSH client (built-in on Windows 10+, macOS, Linux)
A running OpenClaw instance accessible via SSH
A Home Assistant instance with a long-lived access token

Optional (for sub-agents):

claude_run: npm install -g @anthropic-ai/claude-code and run claude once to authenticate
gemini_run: npm install -g @google/gemini-cli and gemini auth login
codex_run: npm install -g @openai/codex and codex login
local_llm_run: any OpenAI-compatible local server:
- LM Studio (recommended, GUI, default port 1234)
- Ollama (ollama serve, port 11434)
- llama.cpp (llama-server, any port)

Installation

Install globally:

npm install -g @elvatis_com/elvatis-mcp

Or use directly via npx (no install required):

npx @elvatis_com/elvatis-mcp

Where Can I Use It?

elvatis-mcp works in every MCP-compatible client. Each client uses its own config file.

Client	Transport	Config file
Claude Desktop / Cowork (Windows MSIX)	stdio	`%LOCALAPPDATA%\Packages\Claude_pzs8sxrjxfjjc\LocalCache\Roaming\Claude\claude_desktop_config.json`
Claude Desktop / Cowork (macOS)	stdio	`~/Library/Application Support/Claude/claude_desktop_config.json`
Claude Code (global, all projects)	stdio	`~/.claude.json`
Claude Code (this project only)	stdio	`.mcp.json` in repo root (already included)
Cursor / Windsurf / other	stdio or HTTP	See app documentation

Claude Desktop and Cowork share the same config file. Claude Code is a separate system.

Configuration

1. Create your `.env` file

cp .env.example .env

# Required
HA_URL=http://your-home-assistant:8123
HA_TOKEN=your_long_lived_ha_token
SSH_HOST=your-openclaw-server-ip
SSH_USER=your-ssh-username
SSH_KEY_PATH=~/.ssh/your_key

# Optional: Local LLM
LOCAL_LLM_ENDPOINT=http://localhost:1234/v1    # LM Studio default
LOCAL_LLM_MODEL=deepseek-r1-0528-qwen3-8b     # or omit to use loaded model

# Optional: Sub-agent models
GEMINI_MODEL=gemini-2.5-flash
CODEX_MODEL=o3

2. Configure your MCP client

Claude Desktop (macOS)

Edit ~/Library/Application Support/Claude/claude_desktop_config.json:

{
  "mcpServers": {
    "elvatis-mcp": {
      "command": "npx",
      "args": ["-y", "@elvatis_com/elvatis-mcp"],
      "env": {
        "HA_URL": "http://your-home-assistant:8123",
        "HA_TOKEN": "your_token",
        "SSH_HOST": "your-openclaw-server-ip",
        "SSH_USER": "your-username",
        "SSH_KEY_PATH": "/Users/your-username/.ssh/your_key"
      }
    }
  }
}

Claude Desktop (Windows MSIX)

Open this file (create it if needed):

%LOCALAPPDATA%\Packages\Claude_pzs8sxrjxfjjc\LocalCache\Roaming\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "elvatis-mcp": {
      "command": "C:\\Program Files\\nodejs\\node.exe",
      "args": ["C:\\path\\to\\elvatis-mcp\\dist\\index.js"],
      "env": {
        "HA_URL": "http://your-home-assistant:8123",
        "HA_TOKEN": "your_token",
        "SSH_HOST": "your-openclaw-server-ip",
        "SSH_USER": "your-username",
        "SSH_KEY_PATH": "C:\\Users\\your-username\\.ssh\\your_key"
      }
    }
  }
}

On Windows, always use full absolute paths. The MSIX sandbox does not resolve ~ or relative paths.

Claude Code (this project)

Copy .mcp.json.example to .mcp.json (gitignored, never committed) and fill in your paths and SSH details. Then copy .env.example to .env for the remaining config.

Claude Code (global)

claude mcp add --scope user elvatis-mcp -- node /path/to/elvatis-mcp/dist/index.js

HTTP Transport (remote clients)

MCP_TRANSPORT=http MCP_HTTP_PORT=3333 npx @elvatis_com/elvatis-mcp

Connect your client to http://your-server:3333/mcp.

Environment Variables

Required

Variable	Description
`HA_URL`	Home Assistant base URL, e.g. `http://192.168.x.x:8123`
`SSH_HOST`	OpenClaw server hostname or IP

Optional

Variable	Default	Description
`HA_TOKEN`	--	Home Assistant long-lived access token
`SSH_PORT`	`22`	SSH port
`SSH_USER`	`chef-linux`	SSH username
`SSH_KEY_PATH`	`~/.ssh/openclaw_tunnel`	Path to SSH private key
`OPENCLAW_GATEWAY_URL`	`http://localhost:18789`	OpenClaw Gateway URL
`OPENCLAW_GATEWAY_TOKEN`	--	Optional Gateway API token
`OPENCLAW_DEFAULT_AGENT`	--	Named agent for `openclaw_run`
`GEMINI_MODEL`	`gemini-2.5-flash`	Default model for `gemini_run`
`CODEX_MODEL`	--	Default model for `codex_run`
`LOCAL_LLM_ENDPOINT`	`http://localhost:1234/v1`	Local LLM server URL (LM Studio default)
`LOCAL_LLM_MODEL`	--	Default local model (omit to use server's loaded model)
`MCP_TRANSPORT`	`stdio`	Transport mode: `stdio` or `http`
`MCP_HTTP_PORT`	`3333`	HTTP port
`SSH_DEBUG`	--	Set to `1` for verbose SSH output
`ELVATIS_DATA_DIR`	`~/.elvatis-mcp`	Directory for persistent usage data (rate limiter)
`RATE_LIMITS`	--	JSON string with per-agent rate limit overrides

Local LLM Setup

elvatis-mcp works with any OpenAI-compatible local server. Three popular options:

LM Studio (recommended for desktop)

Download from lmstudio.ai
Load a model (e.g. Deepseek R1 Qwen3 8B, Phi 4 Mini)
Click "Local Server" in the sidebar and enable it
Server runs at http://localhost:1234/v1 (the default)

Ollama

ollama serve                    # starts server on port 11434
ollama run llama3.2             # downloads and loads model

Set LOCAL_LLM_ENDPOINT=http://localhost:11434/v1 in your .env.

llama.cpp

llama-server -m model.gguf --port 8080

Set LOCAL_LLM_ENDPOINT=http://localhost:8080/v1 in your .env.

Recommended models by task

Model	Size	Best for
Phi 4 Mini	3B	Fast classification, formatting, extraction
Deepseek R1 Qwen3	8B	Reasoning, analysis, prompt splitting
Phi 4 Reasoning Plus	15B	Complex reasoning with quality
GPT-OSS	20B	General purpose, longer responses

Reasoning models (Deepseek R1, Phi 4 Reasoning) wrap their chain-of-thought in <think> tags. elvatis-mcp strips these automatically to give you clean responses.

SSH Setup

The cron, memory, and OpenClaw tools communicate with your server via SSH.

# Verify connectivity
ssh -i ~/.ssh/your_key your-username@your-server "openclaw --version"

# Optional: SSH tunnel for OpenClaw WebSocket gateway
ssh -i ~/.ssh/your_key -L 18789:127.0.0.1:18789 -N your-username@your-server

On Windows, elvatis-mcp automatically resolves the SSH binary to C:\Windows\System32\OpenSSH\ssh.exe and retries on transient connection failures. Set SSH_DEBUG=1 for verbose output.

`/mcp-help` Slash Command

In Claude Code, the /mcp-help slash command shows the full 34-tool routing guide as formatted output:

/mcp-help                           # full guide
/mcp-help openclaw_status           # help for a specific tool
/mcp-help analyze this trading strategy for risk  # routing recommendation

Rate Limiting

Cloud sub-agents (claude_run, codex_run, gemini_run) are rate-limited to prevent runaway costs. Default limits:

Agent	/min	/hr	/day	Est. cost/call
`claude_run`	5	30	200	$0.03
`codex_run`	5	30	200	$0.02
`gemini_run`	10	60	500	$0.01

Local agents (local_llm_run, home_*, openclaw_*) are unlimited.

Usage data persists to ~/.elvatis-mcp/usage.json. Override limits via the RATE_LIMITS env var:

RATE_LIMITS='{"claude_run":{"perMinute":3,"perDay":100}}'

Development

git clone https://github.com/elvatis/elvatis-mcp
cd elvatis-mcp
npm install          # builds automatically via prepare script
cp .env.example .env # fill in your values
node dist/index.js   # starts in stdio mode, waits for MCP client

Build watch mode:

npm run dev

Run integration tests:

npx tsx tests/integration.test.ts

Project layout

src/
  index.ts              MCP server entry, tool registration, transport, dashboard
  config.ts             Environment variable configuration
  dashboard.ts          Status dashboard HTML renderer
  ssh.ts                SSH exec helper (Windows/macOS/Linux)
  spawn.ts              Local process spawner for CLI sub-agents
  tools/
    home.ts             Home Assistant: light, climate, scene, vacuum, sensors
    home-automation.ts  HA automations: list, trigger, enable, disable
    memory.ts           Daily memory log: write, read, search (SSH)
    cron.ts             OpenClaw cron: list, run, status (SSH)
    cron-manage.ts      OpenClaw cron: create, edit, delete, history (SSH)
    openclaw.ts         OpenClaw agent orchestration (SSH)
    openclaw-logs.ts    OpenClaw server log viewer (SSH)
    notify.ts           WhatsApp/Telegram notifications via OpenClaw
    claude.ts           Claude sub-agent (local CLI, for non-Claude clients)
    gemini.ts           Google Gemini sub-agent (local CLI)
    codex.ts            OpenAI Codex sub-agent (local CLI)
    local-llm.ts        Local LLM sub-agent (OpenAI-compatible HTTP)
    local-llm-models.ts LM Studio model management (list/load/unload)
    llama-server.ts     llama.cpp server manager (start/stop/configure)
    file-transfer.ts    File upload/download via SSH
    system-status.ts    Unified health check across all services
    splitter.ts         Smart prompt splitter (multi-strategy)
    split-execute.ts    Plan executor with agent dispatch and rate limiting
    help.ts             Routing guide and task recommender
    routing-rules.ts    Shared routing rules and keyword matching
  rate-limiter.ts       Rate limiting + cost tracking for cloud sub-agents
tests/
  unit.test.ts          42 unit tests (no external services needed)
  integration.test.ts   Live integration tests

Name		Name	Last commit message	Last commit date
Latest commit History 70 Commits
.ai/handoff		.ai/handoff
.claude		.claude
.github/workflows		.github/workflows
benchmarks		benchmarks
src		src
tests		tests
.env.example		.env.example
.gitignore		.gitignore
.mcp.json.example		.mcp.json.example
BENCHMARKS.md		BENCHMARKS.md
CLAUDE.md		CLAUDE.md
CODE_OF_CONDUCT.md		CODE_OF_CONDUCT.md
CONTRIBUTING.md		CONTRIBUTING.md
LICENSE		LICENSE
README.md		README.md
SECURITY.md		SECURITY.md
SKILL.md		SKILL.md
package-lock.json		package-lock.json
package.json		package.json
tsconfig.json		tsconfig.json

Folders and files

Latest commit

History

Repository files navigation

elvatis-mcp

What is this?

What is MCP?

Multi-LLM Architecture

Sub-Agent Comparison

Smart Prompt Splitting

Available Tools (34 total)

Home Assistant (7 tools)

Memory (3 tools)

Cron Automation (7 tools)

OpenClaw Agent (4 tools)

AI Sub-Agents (5 tools)

System Management (4 tools)

Routing and Orchestration (3 tools)

Dashboard

Test Results

Benchmarks

Reference Hardware

Local LLM Inference (LM Studio, Vulkan GPU, --gpu max)

Sub-Agent Comparison (same task, different backends)

Service Latency (system_status)

prompt_split Accuracy (heuristic strategy)

Requirements

Installation

Where Can I Use It?

Configuration

1. Create your .env file

2. Configure your MCP client

Claude Desktop (macOS)

Claude Desktop (Windows MSIX)

Claude Code (this project)

Claude Code (global)

HTTP Transport (remote clients)

Environment Variables

Required

Optional

Local LLM Setup

LM Studio (recommended for desktop)

Ollama

llama.cpp

Recommended models by task

SSH Setup

/mcp-help Slash Command

Rate Limiting

Development

Project layout

License

About

Resources

License

Code of conduct

Contributing

Security policy

Uh oh!

Stars

Watchers

Forks

Releases

Packages 0

Uh oh!

Uh oh!

Contributors

Uh oh!

Languages

Local LLM Inference (LM Studio, Vulkan GPU, `--gpu max`)

1. Create your `.env` file

`/mcp-help` Slash Command

Packages