📌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 LLMs like Claude.

Features

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

getProfile: Fetches a user's profile information by public key.
getKind1Notes: Fetches text notes (kind 1) authored by a user.
getReceivedZaps: Fetches zaps received by a user, including detailed payment information.
getSentZaps: Fetches zaps sent by a user, including detailed payment information.
getAllZaps: Fetches both sent and received zaps for a user, clearly labeled with direction and totals.

All tools support both hex public keys and npub format.

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

Ensure you have Claude for Desktop installed.

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

Add the Nostr server to your configuration:

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

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

Restart Claude for Desktop.

Usage in Claude

Once configured, you can use the Nostr tools with requests like:

"Show me the profile information for npub1..."
"What are the recent posts from npub1...?"
"How many zaps has npub1... received?"
"Show me the zaps sent by npub1..."
"Show me all zaps (both sent and received) for npub1..."

The server handles npub and hex format conversions automatically.

Advanced Usage

Specify custom relays or the number of notes/zaps to fetch:

Custom Relay: "Show me the profile for npub1... using relay wss://relay.damus.io"
Fetch Latest Notes: "Show me the latest 20 notes from npub1..."
Zap Queries with Validation: "Show me all zaps for npub1... with validation enabled"

Limitations

Default 8-second timeout for queries.
Supports only public keys in hex or npub format.
Limited subset of relays used by default.

Implementation Details

Native support for npub format (NIP-19).
NIP-57 compliant zap receipt detection.
Advanced bolt11 invoice parsing.
Smart caching for performance.
NIP-57 validation for zap receipt integrity.

Troubleshooting

Increase the QUERY_TIMEOUT value if queries time out.
Specify different relays if no data is found.
Check Claude's MCP logs for more error information.

Default Relays

The server uses the following relays by default:

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 this server:

Edit the index.ts file in the project root.
Run npm run build to compile.
Restart Claude for Desktop to apply your changes.