nostrhost-mcp
Provides tools generated from the installed YunoHost/NostrHost operation catalogue, enabling AI agents to execute read operations immediately and request write operations that run after approval. It supports NIP-98 client authentication, binds the client npub as the operation actor, and redacts secrets from results.
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.
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_idand execute only after an admin (or NIP-46 owner) approves in the control plane; pollop_statusfor the result.mcp_statusanswers 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-policyand binds the client npub as the operationactor. 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 bynostrhost-core/python3-nostrhost;nostrhost-policyfor NIP-98 verification and redaction;a running control relay (
nostrhost-controlonws://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-toolsAgent 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 pytestTool 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
Remote MCP server for AI.TV creators — delegate account operations to your AI agent over MCP.
MCP server for your apps' tools and custom tools, plus hosted AI agents and approval-gated workflows
Remote MCP server exposing your Node Command fleet (files, shell, processes, browser) to AI hosts.
Zero-secret MCP gateway for AI agents: risk-scored, audited calls with human-in-the-loop approval.
Related MCP Servers
- AlicenseNot gradedqualityCmaintenanceEnables AI clients to securely operate a local machine via MCP or REST, providing file read/write, Playwright browser automation, and shell/service administration.3MIT
- AlicenseNot gradedqualityBmaintenanceEnables 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
- AlicenseNot gradedqualityBmaintenanceEnables 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
- AlicenseNot gradedqualityAmaintenanceExposes 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