MCP HubMCP Hub
AustinKelsay

nostr-mcp-server

by: AustinKelsay

A Model Context Protocol (MCP) server that provides Nostr capabilities to LLMs like Claude.

24created 23/03/2025
Visit
Nostr
LLM

📌Overview

Purpose: The Nostr MCP Server aims to enhance language models, like Claude, by providing functionalities to interact with the Nostr network.

Overview: This server implements a Model Context Protocol (MCP) specifically designed to integrate Nostr capabilities, enabling users to access user profiles, notes, and payment information seamlessly. It supports interactions using both hex public keys and npub formats, ensuring a user-friendly experience.

Key Features:

  • User Profile Retrieval (getProfile): Fetch a user's profile information using their public key, allowing insights into user identity on the Nostr network.

  • Note Retrieval (getKind1Notes): Access text notes authored by a user, facilitating engagement with their content and contributions.

  • Zaps Management (getReceivedZaps, getSentZaps, getAllZaps): Query detailed zap transactions, including received and sent payments, with comprehensive data on amounts and directionality, ensuring clear tracking of interactions.

Nostr MCP Server

A Model Context Protocol (MCP) server that provides Nostr capabilities to large language models like Claude.

Features

This server implements several tools for interacting with the Nostr network:

  1. getProfile: Fetches a user's profile information by public key
  2. getKind1Notes: Fetches text notes (kind 1) authored by a user
  3. getLongFormNotes: Fetches long-form content (kind 30023) authored by a user
  4. getReceivedZaps: Fetches zaps received by a user, including detailed payment information
  5. getSentZaps: Fetches zaps sent by a user, including detailed payment information
  6. getAllZaps: Fetches both sent and received zaps for a user, clearly labeled with direction and totals
  7. searchNips: Search through Nostr Implementation Possibilities (NIPs) with relevance scoring
  8. sendAnonymousZap: Prepare an anonymous zap to a profile or event, generating a lightning invoice for payment

All tools fully support both hex public keys and npub format, with user-friendly display of Nostr identifiers.

Installation

# Clone the repository
git clone https://github.com/austinkelsay/nostr-mcp-server.git
cd nostr-mcp-server

# Install dependencies
npm install

# Build the project
npm run build

Connecting to Claude for Desktop

  1. Install and update Claude for Desktop to the latest version: https://claude.ai/desktop

  2. Edit or create the configuration file:

    For macOS:

    vim ~/Library/Application\ Support/Claude/claude_desktop_config.json

    For Windows:

    notepad %AppData%\Claude\claude_desktop_config.json

  3. Add the Nostr server configuration:

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

    Replace /ABSOLUTE/PATH/TO/ with your actual project path.

  4. Restart Claude for Desktop.

Connecting to Cursor

  1. Install and update Cursor to the latest version: https://cursor.sh/

  2. Edit or create Cursor's configuration file:

    For macOS:

    vim ~/.cursor/config.json

    For Windows:

    notepad %USERPROFILE%\.cursor\config.json

  3. Add the Nostr server configuration:

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

    Replace /ABSOLUTE/PATH/TO/ with your actual project path.

  4. Restart Cursor.

Usage in Claude

After configuration, you can ask Claude to use Nostr tools with requests like:

  • Show profile information for a specific npub key.
  • Get recent posts from a user.
  • Get long-form articles by a user.
  • Query zap statistics (sent, received, all).
  • Search for NIPs about specific topics.
  • Send anonymous or normal zaps with optional comments.

The server automatically converts between npub and hex formats and displays results with user-friendly npub identifiers.

Advanced Usage

  • Specify custom relays, e.g.:
    "Show me the profile for npub1xyz using relay wss://relay.damus.io"

  • Specify number of items to fetch, e.g.:
    "Show me the latest 20 notes from npub1xyz"

  • Include optional comments for anonymous zaps, e.g.:
    "Send an anonymous zap of 500 sats to note1abc with the comment 'Great post!'"

  • Enable extra validation and debugging for zap queries.

  • Control NIP search options such as number of results and full content inclusion.

Limitations

  • Default query timeout is 8 seconds to prevent hanging.
  • Supports only hex format or npub format public keys.
  • Uses a subset of relays by default.

Implementation Details

  • Native npub support using NIP-19 encoding/decoding.
  • NIP-57 compliant zap receipt detection with direction-awareness (sent/received/self).
  • Advanced bolt11 invoice parsing including payment amount extraction.
  • Smart caching for performance with large zap volumes.
  • Total sats calculations with net balance.
  • Optional NIP-57 validation for zap integrity.
  • Anonymous zap support with lightning invoice generation.
  • Supports zapping profiles, events (note IDs), and replaceable events (naddr).
  • Each tool call creates a fresh connection to relays for reliable data retrieval.

Anonymous Zaps

The sendAnonymousZap tool allows sending zaps without revealing the sender’s Nostr identity:

  • Zap appears as from an anonymous user in the recipient’s wallet.
  • Follows NIP-57 protocol but without sender signature.
  • Recipient still receives payment and any included message.
  • Supports profiles (npub/hex), specific events (note/nevent/hex ID), or replaceable events (naddr).
  • Generates a lightning invoice for payment to be used in a Lightning wallet.

Example usage:

Send an anonymous zap of 100 sats to npub1xyz
Send 1000 sats anonymously to note1abc with the comment 'Great post!'

Validates LNURL services according to LNURL-pay (LUD-06) and Lightning Address (LUD-16) specifications, ensuring wallet compatibility.

Troubleshooting

  • Increase the QUERY_TIMEOUT value (default 8 seconds) in source code if queries time out.
  • Specify different relays if no data is returned.
  • Check Claude’s MCP logs for detailed errors.

Default Relays

The server uses these default relays:

  • wss://relay.damus.io
  • wss://relay.nostr.band
  • wss://relay.primal.net
  • wss://nos.lol
  • wss://relay.current.fyi
  • wss://nostr.bitcoiner.social

Development

To modify or extend the server:

  1. Edit source files:

    • index.ts: Main server and tool registration
    • note/note-tools.ts: Profile and notes functionality
    • zap/zap-tools.ts: Zap functionality
    • nips/nips-tools.ts: NIP searching functions
    • utils/: Shared utilities like constants, conversion, formatting, relay management

  2. Run npm run build to compile.

  3. Restart Claude or Cursor to load changes.

Testing

The server includes a comprehensive Jest test suite with unit and integration tests.

Run tests with:

npm test
npm test -- __tests__/basic.test.ts
npm test -- __tests__/integration.test.ts

Tests include:

  • Unit tests for profile formatting, zap receipt processing, profile and note data, zap processing.
  • Integration tests cover interaction with a fully functional in-memory Nostr relay, including publishing and retrieving events, zap receipts, subscriptions, and signature verification.

For more details, see the tests documentation.

Codebase Organization

The codebase is modular:

  • Core server: index.ts
  • Specialized modules:
    • nips/: NIPs search and caching
    • note/: Profile and notes features
    • zap/: Zap handling and anonymous zapping
  • Common utilities in utils/

This structure improves maintainability and eases feature extension. For details, see the respective module documentation.