pebble-index-mcp
This server does not currently have a deployable release on Glama. Follow the repository's setup instructions to install and configure it for your MCP client, including any required credentials and local dependencies.
pebble-index-mcp
MCP bridge that exposes a local Obsidian vault and a Hermes Agent instance to the Pebble Index 01 smart ring's double-click MCP sandbox. Voice captures from the ring are routed by the Pebble app's cloud agent into this server's tools, and the answer comes back as a phone notification.
Architecture
[Index ring] → [Pebble app] → [Pebble cloud agent] → [this MCP server]
├─ vault tools (local files)
├─ ha_control → Home Assistant REST API
├─ ha_announce → assist_satellite.announce
├─ vinyl_lookup → vinyl catalog API
└─ ask_hermes → Hermes API serverThe server speaks MCP over Streamable HTTP (official
mcpSDK, FastMCP).Every request must carry a bearer token; anything else gets 401.
FastMCP's DNS-rebinding protection is on: allowed hosts are loopback plus anything listed in
MCP_ALLOWED_HOSTS.The public exposure is a cloudflared tunnel to the loopback port; no cloud infrastructure is required beyond that.
Related MCP server: Obsidian MCP Server
Components
Path | Role |
|
|
|
|
|
|
|
|
|
|
| FastMCP app: registers the eight tools and the |
Tools
vault_search(query, max_results=5)— case-insensitive text search; returnspath: excerptlines.vault_read(note_path, max_chars=1500)— reads the head of a note.vault_append(note_path, text)— appends a timestamped- HH:MM textline, creating the note if needed.ask_hermes(question)— forwards to the Hermes API server; 60s timeout with an honest acknowledgment on miss.ha_control(command)— smart-home commands:"living room lights on","bedroom off","toggle the hallway","is the living room tv on". Resolves the entity against Home Assistant's state list (room groups win over individual fixtures; ambiguous matches return the candidates instead of guessing), calls the service, and polls the state readback so the confirmation reflects the NEW state. Domains: light, switch, fan, cover, media_player. RequiresHASS_TOKEN. Milliseconds-to-seconds latency; never route smart-home commands throughask_hermes.ha_announce(message)— intercom: speaksmessageon every liveassist_satellitedevice with a pre-announce chime. Offline satellites are skipped (HA returns 200 for announce even when the device is down, so the tool pre-filters). RequiresHASS_TOKEN.ha_music(command)— music control:"play Spiritbox in the basement","play the album Blue Rev in the kitchen","stop the music in the living room". Routes to Music Assistant players (themedia_player.*_2entities) through Home Assistant'splay_mediaservice, verifies the cast started by polling the player'smedia_title, and falls back across artist/track/album interpretations when a search comes back empty. Room map and the no-room default (Voice PE) live inhomeassistant.py. RequiresHASS_TOKENand a running Music Assistant with the Deezer provider.vinyl_lookup(command)— queries the operator's self-hosted vinyl catalog: owned-record search ("do I own Eternal Blue"), a dormancy-weighted random pick, or most-played records. RequiresVINYL_URL.web_search(query, max_results=3)— live web search via the Exa API, composed into a short spoken answer by the configured model. RequiresEXA_API_KEY.
Both answer tools wrap their result in the Pebble app's private coreSchema contract (_meta: {"coreSchema": 1} plus structuredContent carrying a Response semantic result). Without it, the app's completion notification shows the transcription of the question instead of the answer. If the compose step fails, web_search falls back to raw results (the notification then shows the question; the agent still answers in the feed).
Security
Auth: static bearer token (
MCP_BEARER_TOKEN), constant-time compared, required on every request. An empty token fails closed (all requests 401) and logs a warning at startup.Transport: TLS terminates at the tunnel edge; the origin listens on loopback only.
Host validation: DNS-rebinding protection rejects requests whose Host header is not loopback or in
MCP_ALLOWED_HOSTS.Path sandbox: vault tools resolve all paths and require them to stay inside the vault root; symlink escapes are rejected and file opens use
O_NOFOLLOWon the final component. The sandbox guards against accidental and remote misuse; a hostile local process that races a parent-directory swap can still win (documented TOCTOU boundary — the vault is assumed to be a trusted single-user directory).Config is read once at import: rotating the bearer token or changing allowed hosts requires a service restart.
Secrets: the Hermes API key and MCP token live in a 0600 env file outside this repo, never in code, logs, or commits.
Privacy note: recordings routed through the double-click sandbox transit the Pebble app's cloud agent. Single-click captures stay on-device. Sensitive thoughts belong on single-click.
Configuration (env)
Var | Default | Purpose |
| — | Required. Vault root for the file tools |
|
| Listen address |
| — | Required; request auth token |
| — | Comma-separated extra allowed Host values (the public tunnel hostname goes here) |
|
| ask_hermes target |
| — | API server bearer key |
|
| Model alias sent upstream (map it to a cheap model via the API server's |
| — | Exa API key for |
|
| Home Assistant base URL for |
| — | Home Assistant long-lived access token for |
| — | Base URL of a vinyl catalog API exposing |
| — | Optional path to a text file replacing the generic cloud-agent persona |
HERMES_API_URL accepts any OpenAI-compatible chat completions endpoint, so
ask_hermes works against OpenRouter directly, Ollama, or any other
compatible API — Hermes is just the default.
Development
python3 -m venv .venv
.venv/bin/pip install -e ".[dev]"
.venv/bin/pytest -vRun locally: set the env vars above and python -m pebble_index_mcp.server.
Deployment
deploy/ contains a systemd user unit template and a cloudflared tunnel
template (hostname and credentials filled in on the host, not in this repo).
See docs/ring-checklist.md for the phone-side setup and test matrix.
License
MIT — see LICENSE.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
This server cannot be deployed
Maintenance
Related MCP Connectors
Search, read, and write your Apple Notes from ChatGPT/Claude via a local Mac agent + MCP relay.
Voice notes that organize themselves. Capture by Siri, AI auto-tags, semantic search retrieves.
Connect AI assistants to your GitHub-hosted Obsidian vault to seamlessly access, search, and analy…
Notes and actions in one app. Let Claude or ChatGPT read and update them.
Related MCP Servers
- AlicenseAqualityDmaintenanceEnables AI assistants to interact with Obsidian vaults for creating, reading, searching, and managing notes, daily notes, TODOs, session reports, and backlinks through both stdio and HTTP/SSE transports.103,713 npm4MIT
- AlicenseNot gradedqualityDmaintenanceEnables AI assistants to manage Obsidian notes via local REST API, supporting file CRUD, search, commands, and periodic notes.7,721 npm7Apache 2.0
- AlicenseBqualityDmaintenanceEnables AI assistants to search, create, and manage notes in an Obsidian vault via 40+ local tools.5221 npmMIT
- FlicenseNot gradedqualityDmaintenanceEnables AI assistants to manage and search Obsidian notes, folders, metadata, and links directly.-