Nostr MCP Client

This module implements a Model Context Protocol (MCP) client over the Nostr network. It enables agents to discover, invoke, and manage tools in a decentralized manner using the Nostr protocol for communication.

class agentstr.nostr_mcp_client.NostrMCPClient(mcp_pubkey: str, nostr_client: NostrClient | None = None, relays: list[str] | None = None, private_key: str | None = None, nwc_str: str | None = None)

Bases: object

Client for interacting with Model Context Protocol (MCP) servers on Nostr.

Discovers and calls tools from MCP servers, handling payments via NWC when needed.

Examples

Basic usage demonstrating listing tools and calling one:

import asyncio
from agentstr import NostrMCPClient

relays = ["wss://relay.damus.io"]
mcp_client = NostrMCPClient(
    mcp_pubkey="npub1example...",  # MCP server pubkey
    relays=relays,
    private_key="nsec1example...",  # your private key
)

async def main():
    tools = await mcp_client.list_tools()
    print("Available tools:", tools)
    result = await mcp_client.call_tool("add", {"a": 1, "b": 2})
    print("1 + 2 =", result)

asyncio.run(main())

Full runnable script: mcp_client.py

__init__(mcp_pubkey: str, nostr_client: NostrClient | None = None, relays: list[str] | None = None, private_key: str | None = None, nwc_str: str | None = None)

Initialize the MCP client.

Parameters:

• mcp_pubkey – Public key of the MCP server to interact with.

• 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).

async list_tools() → dict[str, Any] | None

Retrieve the list of available tools from the MCP server.

Returns:

Dictionary of tools with their metadata, or None if not found.

async call_tool(name: str, arguments: dict[str, Any], timeout: int = 60) → dict[str, Any] | None

Call a tool on the MCP server with provided arguments.

Parameters:

• name – Name of the tool to call.

• arguments – Dictionary of arguments for the tool.

• timeout – Timeout in seconds for receiving a response.

Returns:

Response dictionary from the server, or None if no response.