Nostr Data Interface Service

A Model Context Protocol (MCP) intermediary layer facilitating comprehensive interaction with the Nostr ecosystem for Large Language Models (LLMs) such as Claude.

https://github.com/user-attachments/assets/1d2d47d0-c61b-44e2-85be-5985d2a81c64

Capabilities Overview

This service exposes 18 distinct operations for engaging with Nostr entities:

Data Retrieval & Exploration Tools

1. getProfile: Retrieves public identity details based on a public key address.
2. getKind1Notes: Fetches standard text messages (event kind 1) authored by a specific user.
3. getLongFormNotes: Accesses long-form articles (event kind 30023) published by an identity.
4. getReceivedZaps: Queries incoming zap events, detailing associated monetary transfers.
5. getSentZaps: Queries outgoing zap events, detailing payment initiation.
6. getAllZaps: Consolidates both incoming and outgoing zap records with directional labeling.
7. searchNips: Performs targeted searches across documented Nostr Improvement Proposals (NIPs) with scoring based on relevance.

Identity Administration Tools

1. createKeypair: Generates new cryptographic key pairs, outputting results in hex and/or user-friendly npub/nsec formats.
2. createProfile: Constructs and prepares a new identity metadata event (kind 0).
3. updateProfile: Modifies and stages existing identity metadata associated with a kind 0 event.

Content Publication & Signing Tools

1. createNote: Drafts unsigned kind 1 event data, incorporating content and metadata tags.
2. signNote: Applies cryptographic signature to a note event payload using a provided private key.
3. publishNote: Disseminates a pre-signed event payload across configured Nostr relays.
4. postNote: An integrated function executing creation, signing, and relaying of an authenticated note using a private key.

Anonymity-Focused Tools

1. sendAnonymousZap: Prepares a lightning payment zap directed at a profile or event without linking the source identity.
2. postAnonymousNote: Publishes a text event using a transient, randomly generated keypair for non-attributable posting.

NIP-19 Encoding Utilities

1. convertNip19: Translates between various NIP-19 encoded forms (e.g., hex, npub, nprofile, nevent).
2. analyzeNip19: Decodes and provides a structural breakdown of any provided NIP-19 entity string.

All operational functions natively accommodate both raw hexadecimal public keys and the standardized npub identifier scheme, ensuring streamlined user interaction.

Deployment Instructions

Method 1: Install via npm (Recommended)

bash npm install -g nostr-mcp-server

Method 2: Install from Source

bash

Clone the repository source

git clone https://github.com/austinkelsay/nostr-mcp-server.git cd nostr-mcp-server

Install necessary dependencies

npm install

Compile the TypeScript project

npm run build

Integration with LLM Environments

Configuring for Claude Desktop Client

1. Ensure you have the most recent version of Claude for Desktop.

2. Modify or establish the configuration file specific to your operating system:

macOS: bash vim ~/Library/Application\ Support/Claude/claude_desktop_config.json

Windows: bash notepad %AppData%\Claude\claude_desktop_config.json

1. Integrate the Nostr service definition into the mcpServers block:

If using npm installation:

{ "mcpServers": { "nostr": { "command": "npx", "args": [ "nostr-mcp-server" ] } } }

If using source installation:

{ "mcpServers": { "nostr": { "command": "node", "args": [ "/ABSOLUTE/PATH/TO/nostr-mcp-server/build/index.js" ] } } }

Note: For source setups, substitute /ABSOLUTE/PATH/TO/ with the actual installation directory.

1. Re-launch the Claude application.

Configuring for Cursor IDE

1. Verify Cursor is installed and current.

2. Edit or create the configuration file located at:

macOS: bash vim ~/.cursor/config.json

Windows: bash notepad %USERPROFILE%.cursor\config.json

1. Embed the Nostr server configuration into the mcpServers section:

If using npm installation:

{ "mcpServers": { "nostr": { "command": "npx", "args": [ "nostr-mcp-server" ] } } }

If using source installation:

{ "mcpServers": { "nostr": { "command": "node", "args": [ "/ABSOLUTE/PATH/TO/nostr-mcp-server/build/index.js" ] } } }

Remember to set the correct absolute path for source installations.

1. Restart Cursor to initialize the new tool.

Configuring for Goose Client

1. Ensure Goose is installed and operational.

2. Update your Goose profile configuration (usually found at ~/.config/goose/profiles.yaml) by adding an entry to the mcpServers list within your desired profile block:

If using npm installation: yaml profiles: default: provider: # ... existing provider settings model: # ... existing model settings mcpServers: - name: nostr command: npx args: - nostr-mcp-server

If using source installation: yaml profiles: default: provider: # ... existing provider settings model: # ... existing model settings mcpServers: - name: nostr command: node args: - /ABSOLUTE/PATH/TO/nostr-mcp-server/build/index.js

Update the placeholder path for source deployments.

1. Either restart Goose or perform a configuration reload.

2. Confirm connectivity by querying Goose directly, for instance: "Query Goose regarding available Nostr MCP instruments."

Operational Examples within Claude

Once integrated, LLM requests can invoke these capabilities:

Data Retrieval & Exploration

• "Fetch the profile attributes for npub1qny3tkh0acurzla8x3zy4nhrjz5zd8ne6dvrjehx9n9hr3lnj08qwuzwc8"
• "What are the most recent text posts associated with npub1qny3tkh0acurzla8x3zy4nhrjz5zd8ne6dvrjehx9n9hr3lnj08qwuzwc8?"
• "Retrieve long-form content items published by npub1qny3tkh0acurzla8x3zy4nhrjz5zd8ne6dvrjehx9n9hr3lnj08qwuzwc8"
• "Quantify the zaps received by npub1qny3tkh0acurzla8x3zy4nhrjz5zd8ne6dvrjehx9n9hr3lnj08qwuzwc8"
• "Detail the outgoing zaps originating from npub1qny3tkh0acurzla8x3zy4nhrjz5zd8ne6dvrjehx9n9hr3lnj08qwuzwc8"
• "Present a comprehensive ledger of all zaps (inbound and outbound) for npub1qny3tkh0acurzla8x3zy4nhrjz5zd8ne6dvrjehx9n9hr3lnj08qwuzwc8"
• "Execute a search across NIP documents for terms related to 'zaps'."
• "Identify NIP specifications relevant to extended content formats."
• "Display NIP-23 specifications, including all textual content."

Identity & Profile Administration

• "Generate a fresh Nostr cryptographic key pair."
• "Produce a key pair providing output in both hexadecimal and npub formats."
• "Initialize a new Nostr profile defining the name as 'Alice' and bio as 'A dedicated Bitcoiner and software engineer'."
• "Modify the current identity metadata to include an avatar URL ('https://example.com/avatar.jpg') and a personal website ('https://alice.dev')."

Content Creation & Dissemination

• "Draft an unsigned kind 1 event containing the message 'Greetings to the decentralized web!' along with tags #introduction and #nostr."
• "Apply cryptographic signing to this note event using private key nsec1xyz..."
• "Relay this signed event payload to endpoints wss://relay.damus.io and wss://nos.lol."
• "Perform an end-to-end authenticated note publication using the content 'Good morning, Nostr community! ☀️' and private key nsec1xyz..."

Anonymous Transactions

• "Dispatch an untraceable lightning zap of 100 sats targeting the profile npub1qny3tkh0acurzla8x3zy4nhrjz5zd8ne6dvrjehx9n9hr3lnj08qwuzwc8"
• "Remit 1000 sats anonymously toward note1abcdef... accompanied by the supporting comment 'Excellent commentary!'"
• "Publish a message to Nostr anonymously: 'Sharing fleeting thoughts.'"
• "Draft an untraceable publication featuring the tags #bitcoin and #privacy."

NIP-19 Entity Analysis & Translation

• "Translate the hexadecimal public key 06639334b39dd9cf4aa1323375931bec1d6cd43b5de30af7b70b08262e5f6e3f into npub format."
• "Convert npub1qny3tkh0acurzla8x3zy4nhrjz5zd8ne6dvrjehx9n9hr3lnj08qwuzwc8 to its underlying hex representation."
• "Transform this note ID into its nevent encoding, incorporating relay discovery hints."
• "Perform a deep analysis on the entity nprofile1qqsw3dy8cpu... to ascertain its structure and type."
• "Decode and scrutinize the contents of the NIP-19 entity labeled nevent1qqs..."

The system abstracts key conversion complexity, accepting either hex or npub identifiers interchangeably in input parameters.

Anonymous Note Posting Details

The postAnonymousNote function enables publication to Nostr without attaching the user's primary identity. Crucial operational notes:

• The published event will attribute its source to a randomly generated, single-use cryptographic key pair.
• This transient private key is immediately discarded post-signing; it is never persisted.
• The resulting event identifier and the temporary public key are returned in the operation's response.
• Custom metadata tags can be optionally associated with the anonymous post.
• By default, the note is broadcast to a selection of high-availability relays to maximize reach.

Examples:

"Release an anonymous message stating 'Testing the untraceable posting capability!'" "Initiate an untraceable post with content 'Evaluating anonymity features of this decentralized platform' and tags #test #stealth" "Broadcast content anonymously to the network: 'Observations intended for public eyes only, not my identity'"

For precise delivery, you may specify relay endpoints:

"Distribute an anonymous note to relay wss://relay.damus.io containing the text 'A silent greeting to all connected peers!'"

This capability is advantageous for: - Isolated testing of publication workflows. - Disseminating sensitive or ephemeral information. - Generating content that should lack persistent identity linkage.

Identity & Profile Management Deep Dive

The service offers robust tooling for cryptographic key management and metadata stewardship:

Key Generation

createKeypair employs the secp256k1 elliptic curve for generating cryptographically sound Nostr key pairs. Output format selection is granular:

"Generate a new Nostr key pair, providing both hex and npub/nsec representations." "Request key generation yielding only hexadecimal keys." "Output the generated keys exclusively in npub/nsec format."

Profile Lifecycle Management

Profile management centers around the Nostr kind 0 event structure, supporting all standardized metadata fields:

• Textual Data: Setting display names, unique usernames, and descriptive biographies.
• Visual Assets: Specifying URLs for profile avatars and banner images.
• Verification: Configuring NIP-05 verifiable identity strings.
• Monetization: Encoding Lightning payment handles via LUD-16 (Lightning Address) and LUD-06 (LNURL).
• Web Links: Incorporating external website URLs and social media pointers.

Examples:

"Establish a new profile entity with display name 'Alice', biography 'Bitcoin evangelist and software architect', and avatar 'https://example.com/alice.jpg'" "Update identity metadata to feature website 'https://alice.dev' and Lightning Address 'alice@getalby.com'"

Authenticated Content Publishing Workflows

Granular Note Operations

For advanced control over the publication pipeline:

• createNote: Generates the raw, unsigned event structure populated with content and tags.
• signNote: Applies the necessary digital signature using a private key.
• publishNote: Transmits the fully signed event to the designated relay cluster.

This separation of concerns enables: - Preparation of events offline before signing. - Optimized batch processing of multiple notes. - Integration with external, dedicated signing authorities. - Flexible relay selection for targeted dissemination.

Unified Posting Command

The postNote function streamlines the three sequential steps above into one execution:

"Publish a status update: 'Excited about the latest block reward!' using my private key nsec1xyz..." "Generate and post content: 'Just finalized the Q3 roadmap' including tags #strategy and #development." "Relay the message 'The weather is fantastic today ☀️' with tags #photography #nature, explicitly targeting relay wss://relay.damus.io"

Key attributes: - Identity Assurance: Events are verifiably linked to your established Nostr identity. - Key Format Adaptability: Accepts private keys in both hex and nsec encoding. - Tagging Support: Full capacity to include hashtags, mentions, and arbitrary metadata. - Relay Targeting: Fine-grained control over which relays receive the published data.

Advanced Query Parameters

You can refine data fetching operations by specifying relays explicitly:

• "Retrieve the entity details for npub1qny3tkh0acurzla8x3zy4nhrjz5zd8ne6dvrjehx9n9hr3lnj08qwuzwc8 utilizing relay wss://relay.damus.io exclusively."

You can also constrain result volumes:

• "Fetch the most recent 20 textual posts from npub1qny3tkh0acurzla8x3zy4nhrjz5zd8ne6dvrjehx9n9hr3lnj08qwuzwc8."

For anonymous zaps, supplemental data like comments and target specificity can be defined:

• "Initiate an untraceable zap of 500 sats towards note1abcdef... including the payload message 'Excellent work on this!'"
• "Transfer 1000 sats anonymously to nevent1qys... directing transmission via wss://relay.damus.io."

Zap query operations support activation of supplemental checks:

• "Examine all zaps associated with npub1qny3tkh0acurzla8x3zy4nhrjz5zd8ne6dvrjehx9n9hr3lnj08qwuzwc8, enabling full validation and debug output."

NIP search functions allow result limiting and content inclusion:

• "Search for NIPs pertaining to 'zaps' and return the complete specification text."
• "List the top 5 NIPs relevant to decentralized relay networks."
• "Identify NIPs concerning encryption standards; limit results to 15 items."

Operational Constraints

• All network queries are subject to a default execution limit of 8 seconds to prevent resource lockup.
• Public key inputs must be provided as either raw hexadecimal strings or NIP-19 encoded npub format.
• The system defaults to a curated, pre-configured list of public relays for operations.

Technical Architecture

• Core functionality powered by snstr: a performant, modern TypeScript library for Nostr protocol handling.
• Native, robust management of NIP-19 encoding and decoding processes.
• Compliance with NIP-57 for zap receipt handling, accurately tracking payment direction (sent/received/internal).
• Advanced parsing of bolt11 invoices to extract precise payment quantities.
• Integrated optimization layer employing smart caching to accelerate repeated data requests, especially for high-volume zap data.
• Comprehensive aggregation and net balance computation for all recorded zap transactions.
• Optional execution of NIP-57 compliance checks for enhanced zap receipt security verification.
• Support for initiating anonymous zaps alongside automated lightning invoice production.
• Versatile target support for zapping: profiles (npub/hex), specific events (note/nevent/hex ID), and replaceable events (naddr).
• Each tool invocation establishes an independent, isolated connection to the relays, prioritizing data retrieval reliability.
• Extensive unit and integration testing ensures stability and correct protocol adherence.

Anonymous Zap Mechanism

The sendAnonymousZap function allows for lightning payments without revealing the sender's Nostr identity.

• The payment receiver's wallet will register the transaction as originating from an unidentified entity.
• The underlying NIP-57 structure is maintained, but the sender signature component is omitted.
• Payment fulfillment and any included descriptive messages are still processed.
• Targets can be profiles (via npub/hex), events (note/nevent/hex), or time-bound events (naddr).
• The service returns the necessary lightning invoice data for external wallet fulfillment.

Examples:

"Dispatch an untraceable zap of 100 satoshis to npub1qny3tkh0acurzla8x3zy4nhrjz5zd8ne6dvrjehx9n9hr3lnj08qwuzwc8." "Send 1000 sats anonymously to note1abcdef... with the annotation 'Exceptional content!'"

The service incorporates thorough validation for LNURL services, adhering strictly to LNURL-pay (LUD-06) and Lightning Address (LUD-16) standards to maximize wallet compatibility.

Diagnostic Guidance

• Timeouts (exceeding the 8-second threshold) can potentially be mitigated by modifying the QUERY_TIMEOUT constant within the source code.
• If data retrieval yields no results, investigate alternative, perhaps less common, relay endpoints.
• Consult the LLM's MCP execution logs for detailed operational error reporting.

Default Relay Endpoints

The server is initialized to use the following public relays: - wss://relay.damus.io - wss://relay.nostr.band - wss://relay.primal.net - wss://nos.lol - wss://purplerelay.com - wss://nostr.land

Development & Extension Guidelines

To modify or extend this service:

1. Navigate to the relevant source file for modification:
2. index.ts: Core bootstrap and tool registration registry.
3. profile/profile-tools.ts: Handles identity bootstrapping, key generation, and profile record management (See Documentation).
4. note/note-tools.ts: Manages note lifecycle: drafting, signing, relaying, and retrieval (See Documentation).
5. zap/zap-tools.ts: Contains all logic related to processing and generating zap transactions (See Documentation).
6. nips/nips-tools.ts: Implements the NIP discovery and searching mechanism (See Documentation).

7. utils/: Directory for shared utility modules:

   • constants.ts: Definition of static values and relay configurations.
   • conversion.ts: Utilities for transforming between NIP-19 entities (hex/npub/nprofile/nevent/naddr).
   • formatting.ts: Helpers for standardizing output presentation.
   • nip19-tools.ts: Specialized tools for NIP-19 decoding and structural inspection.
   • pool.ts: Manages persistent and transient Nostr connection infrastructure.
   • ephemeral-relay.ts: An in-memory mock relay implementation used for isolated testing.

8. Execute the build script to recompile:

bash npm run build

1. Ensure the LLM environment (Claude Desktop/Cursor) is restarted to load the updated tool binary.

Verification Suite

We maintain an extensive test suite utilizing Jest, covering both functional validation and protocol-level integration testing:

bash

Execute all defined test scenarios

npm test

Execute tests targeting specific files, e.g., basic functionality checks

npm test -- tests/basic.test.ts

Execute tests simulating live network interaction

npm test -- tests/integration.test.ts

The testing framework encompasses:

Unit Validation

• basic.test.ts - Tests for simple data structure formatting and zap receipt parsing fidelity.
• profile-notes-simple.test.ts - Validation of core profile and note object structures.
• profile-tools.test.ts - Verification of keypair generation and identity management logic.
• note-creation.test.ts - Testing the sequence of note creation, signing, and publication initiation.
• note-tools-functions.test.ts - Comprehensive testing of note payload assembly, signing utility functions, and relay submission logic.
• note-tools-unit.test.ts - Isolated unit tests for internal note formatting helpers.
• profile-postnote.test.ts - Validates the authenticated note posting routine using pre-existing credentials.
• zap-tools-simple.test.ts - Initial tests for zap processing and anonymous zap preparation.
• zap-tools-tests.test.ts - Deep validation of zap data parsing, integrity checking, and directionality.
• search-nips-simple.test.ts - Tests for NIP search execution and result scoring mechanisms.
• nip19-conversion.test.ts - Rigorous validation of NIP-19 encoding/decoding mechanisms (includes 28 distinct assertion cases).

Integration Testing

• integration.test.ts - Tests interaction pathways against our simulated environment, including:
• Successful dispatching of profile updates.
• Creation and subsequent retrieval of fresh text notes.
• Simulation of zap receipt notifications.

• Event filtering logic against the mock relay.

• websocket-integration.test.ts - Tests robustness of actual WebSocket communication with an external Nostr relay:

• Event transmission over established socket connections.
• Subscription management using complex filter sets.
• Proper lifecycle management (closing subscriptions).
• Verification that improperly signed events are correctly discarded by the relay.

Testing Environment Foundation

• All integration tests leverage ephemeral-relay.ts—a fully compliant, in-memory implementation of a Nostr relay server.
• Cryptographic signing and verification leverage the snstr library.
• Tests are designed for clean execution, ensuring complete resource release and suppressing non-essential console output.
• Automated management of WebSocket connections includes built-in timeout handling.
• The testing sandbox is self-contained, removing dependencies on external network availability.

Consult tests/README.md for exhaustive details regarding the test suite architecture.

Codebase Structure

The service architecture follows a modular approach: - index.ts: Entry point, configuring the core server and registering all available tools. - Dedicated directories for specialized concerns: - profile/: Management of identity keys, key pair generation, and profile metadata configuration. - note/: Functionality dedicated to note event creation, cryptographic signing, relaying, and content retrieval. - zap/: Logic governing the handling, validation, and anonymous initiation of zaps. - nips/: Components responsible for NIP searching and result caching. - The utils/ directory houses shared infrastructure and helpers.

This organizational methodology enhances long-term maintainability, minimizes code redundancy, and streamlines the process of introducing new features. Refer to the README file within each module directory for specific feature documentation.