Skip to main content
Glama

nostrhost-mcp

Thin MCP protocol adapter over the NostrHost native operation model.

MCP is an interface, not an authority boundary. This package owns the MCP protocol, generated tool schemas, NIP-98 client authentication, result redaction and transport — while authority, policy, approvals, execution and state all live in NostrHost itself (the installed fork + control plane).

See docs/MCP-TRANSITION.md in the imattau/nostrhost umbrella for the full plan and the frozen yunohost-mcp feature inventory.

Design

Claude / Codex / OpenCode
          ↓
         MCP
          ↓
    nostrhost-mcp         ← this package (thin, no root, no policy)
          ↓
   signed kind-2200 operation request
          ↓
       control relay      ws://127.0.0.1:4848
          ↓
    nostr-operationsd     ← authority/policy/approval/execution/audit
          ↓
   2201/2203/2204/2205 chain events  (correlated by request id)
  • Tools are generated from the installed fork's operation catalogue (yunohost.nostr_operations.operation_catalog()) — the registry is the single source of truth, shared with the CLI, API and Admin forms.

  • Read operations run immediately (un-gated). Write operations return approval_required + operation_id and execute only after an admin (or NIP-46 owner) approves in the control plane; poll op_status for the result.

  • mcp_status answers locally, without submitting an operation: is this endpoint reachable, and which identity (if any) is this call recognised as. Use it instead of a registry op to sanity-check a new connection — it still works even if the control relay or executor is down.

  • HTTP transport verifies each request's NIP-98 header against nostrhost-policy and binds the client npub as the operation actor. It binds loopback only — the MCP server is never exposed publicly.

  • Redaction strips secret-shaped values from results before they reach the AI model.

Related MCP server: omp A2A Bridge

On-node prerequisites

The adapter depends on the installed NostrHost fork and policy library (like the CLI and nostr-api):

  • the fork package (yunohost.nostr_operations, yunohost.nostr_mcp_adapter, yunohost.nostr_identity.publish_to_relay, yunohost.nostrhost.events) — shipped by nostrhost-core / python3-nostrhost;

  • nostrhost-policy for NIP-98 verification and redaction;

  • a running control relay (nostrhost-control on ws://127.0.0.1:4848) and the operation executor (nostr-operationsd).

Usage

# stdio (Claude Code / Codex / OpenCode local MCP)
nostrhost-mcp serve --stdio

# streamable HTTP on loopback (OpenCode Web → localhost)
nostrhost-mcp serve --http 8930

# override keys/relay (defaults come from the fork operator config)
nostrhost-mcp serve --stdio --agent-sk <hex> --control-relay ws://127.0.0.1:4848 --server-pubkey <hex>

# print the generated catalogue
nostrhost-mcp list-tools

Agent config for MCP clients (e.g. opencode.json):

{ "mcpServers": { "nostrhost": { "command": "nostrhost-mcp", "args": ["serve", "--stdio"] } } }

Deploy

deploy/nostrhost-mcp.service runs the adapter as a loopback streamable HTTP server (127.0.0.1:8930). A reverse proxy (Caddy) fronts it when the endpoint is exposed on a public hostname; name that hostname in /etc/nostrhost/mcp.env (NOSTRHOST_MCP_ALLOWED_HOSTS=mcp.example.test, space/comma separated) or the MCP SDK's DNS-rebinding protection rejects proxied requests with 421. The unit reads the fork's operator config for its key and control relay, so it needs nostrhost-core + nostrhost-runtime installed.

Installable as the python3-nostrhost-mcp APT package (see packaging/packages.yml in the umbrella), which provisions the adapter into /opt/nostrhost/venv and ships this unit (not auto-enabled).

Development

uv sync
PYTHONPATH=.../forks/yunohost/src  # the fork, for on-host integration
uv run pytest

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      Not graded
      quality
      B
      maintenance
      Enables a remote omp client to invoke the host omp's tools over HTTP using the MCP protocol, with no LLM API calls on the host.
      MIT
    • A
      license
      Not graded
      quality
      B
      maintenance
      Enables AI assistants such as Claude and Codex to read and write Anytype objects through a local loopback MCP endpoint secured by a bearer token.
      MIT
    • A
      license
      Not graded
      quality
      A
      maintenance
      Exposes a governed, OAuth-gated MCP endpoint that lets web AI clients such as Claude, ChatGPT, Grok, and Postman work directly on your local machine. It enables file reading and editing, whitelisted shell commands, search, Git and SQLite access, browser and DevTools automation, background tasks, localhost fetches, clipboard, notifications, and port management.
      MIT