Nostr MCP Server

This module implements a Model Control Protocol (MCP) server that runs over the Nostr network. It allows entities to expose their tools and handle incoming requests from other agents in a decentralized manner using the Nostr protocol.

agentstr.nostr_mcp_server.tool(**kwargs)[source]

Decorator to mark a function as a tool with extra parameters for registration via add_tool.

Usage:

@tool(name=”mytool”, description=”desc”, satoshis=100) def myfunc(…): …

The parameters are attached to the function as __tool_params__.

agentstr.nostr_mcp_server.stringify_result(result: Any) → str[source]

Convert a result to a string.

class agentstr.nostr_mcp_server.NostrMCPServer(display_name: str, nostr_client: NostrClient | None = None, relays: list[str] | None = None, private_key: str | None = None, nwc_str: str | None = None, tools: list[Callable[[...], Any]] = [])[source]

Bases: object

Model Context Protocol (MCP) server running on the Nostr protocol.

Registers and manages tools that can be called by clients via direct messages, with optional payment requirements handled through NWC.

__init__(display_name: str, nostr_client: NostrClient | None = None, relays: list[str] | None = None, private_key: str | None = None, nwc_str: str | None = None, tools: list[Callable[[...], Any]] = [])[source]

Initialize the MCP server.

Parameters:

  • display_name – Display name of the server.

  • nostr_client – Existing NostrClient instance (optional).

  • relays – List of Nostr relay URLs (if no client provided).

  • private_key – Nostr private key (if no client provided).

  • nwc_str – Nostr Wallet Connect string for payments (optional).

add_tool(fn: Callable[[...], Any], name: str | None = None, description: str | None = None, satoshis: int | None = None)[source]

Register a tool with the server.

Parameters:

  • fn – The function to register as a tool.

  • name – Name of the tool (defaults to function name).

  • description – Description of the tool (optional).

  • satoshis – Satoshis required to call the tool (optional).

async list_tools() → dict[str, Any][source]

List all registered tools and their metadata.

Returns:

Dictionary containing a list of tools with their names, descriptions, input schemas, and required satoshis.

async call_tool(name: str, arguments: dict[str, Any]) → str | None[source]

Execute a registered tool by name with provided arguments.

Parameters:

  • name – Name of the tool to call.

  • arguments – Dictionary of arguments for the tool.

Returns:

Result of the tool execution.

Raises:

ToolError – If the tool is not found.

async start()[source]

Start the MCP server, updating metadata and listening for direct messages.