local-only server
The server can only run on the client’s local machine because it depends on local resources.
Nostr MCP Server
A Model Context Protocol (MCP) server that provides Nostr capabilities to LLMs like Claude.
https://github.com/user-attachments/assets/1d2d47d0-c61b-44e2-85be-5985d2a81c64
Features
This server implements several tools for interacting with the Nostr network:
getProfile
: Fetches a user's profile information by public keygetKind1Notes
: Fetches text notes (kind 1) authored by a usergetLongFormNotes
: Fetches long-form content (kind 30023) authored by a usergetReceivedZaps
: Fetches zaps received by a user, including detailed payment informationgetSentZaps
: Fetches zaps sent by a user, including detailed payment informationgetAllZaps
: Fetches both sent and received zaps for a user, clearly labeled with direction and totalssearchNips
: Search through Nostr Implementation Possibilities (NIPs) with relevance scoringsendAnonymousZap
: 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
Connecting to Claude for Desktop
- Make sure you have Claude for Desktop installed and updated to the latest version.
- Configure Claude for Desktop by editing or creating the configuration file:For macOS:For Windows:CopyCopy
- Add the Nostr server to your configuration:Be sure to replaceCopy
/ABSOLUTE/PATH/TO/
with the actual path to your project. - Restart Claude for Desktop.
Connecting to Cursor
- Make sure you have Cursor installed and updated to the latest version.
- Configure Cursor by creating or editing the configuration file:For macOS:For Windows:CopyCopy
- Add the Nostr server to your configuration:Be sure to replaceCopy
/ABSOLUTE/PATH/TO/
with the actual path to your project. - Restart Cursor.
Usage in Claude
Once configured, you can ask Claude to use the Nostr tools by making requests like:
- "Show me the profile information for npub1qny3tkh0acurzla8x3zy4nhrjz5zd8ne6dvrjehx9n9hr3lnj08qwuzwc8"
- "What are the recent posts from npub1qny3tkh0acurzla8x3zy4nhrjz5zd8ne6dvrjehx9n9hr3lnj08qwuzwc8?"
- "Show me the long-form articles from npub1qny3tkh0acurzla8x3zy4nhrjz5zd8ne6dvrjehx9n9hr3lnj08qwuzwc8"
- "How many zaps has npub1qny3tkh0acurzla8x3zy4nhrjz5zd8ne6dvrjehx9n9hr3lnj08qwuzwc8 received?"
- "Show me the zaps sent by npub1qny3tkh0acurzla8x3zy4nhrjz5zd8ne6dvrjehx9n9hr3lnj08qwuzwc8"
- "Show me all zaps (both sent and received) for npub1qny3tkh0acurzla8x3zy4nhrjz5zd8ne6dvrjehx9n9hr3lnj08qwuzwc8"
- "Search for NIPs about zaps"
- "What NIPs are related to long-form content?"
- "Show me NIP-23 with full content"
- "Send an anonymous zap of 100 sats to npub1qny3tkh0acurzla8x3zy4nhrjz5zd8ne6dvrjehx9n9hr3lnj08qwuzwc8"
- "Send 1000 sats to note1abcdef... with a comment saying 'Great post!'"
The server automatically handles conversion between npub and hex formats, so you can use either format in your queries. Results are displayed with user-friendly npub identifiers.
Advanced Usage
You can specify custom relays for any query:
- "Show me the profile for npub1qny3tkh0acurzla8x3zy4nhrjz5zd8ne6dvrjehx9n9hr3lnj08qwuzwc8 using relay wss://relay.damus.io"
You can also specify the number of notes or zaps to fetch:
- "Show me the latest 20 notes from npub1qny3tkh0acurzla8x3zy4nhrjz5zd8ne6dvrjehx9n9hr3lnj08qwuzwc8"
For anonymous zaps, you can include optional comments and specify the target type:
- "Send an anonymous zap of 500 sats to note1abcdef... with the comment 'Great post!'"
- "Send 1000 sats anonymously to nevent1qys... using relay wss://relay.damus.io"
For zap queries, you can enable extra validation and debugging:
- "Show me all zaps for npub1qny3tkh0acurzla8x3zy4nhrjz5zd8ne6dvrjehx9n9hr3lnj08qwuzwc8 with validation and debug enabled"
For NIP searches, you can control the number of results and include full content:
- "Search for NIPs about zaps with full content"
- "Show me the top 5 NIPs about relays"
- "What NIPs are related to encryption? Show me 15 results"
Limitations
- The server has a default 8-second timeout for queries to prevent hanging
- Only public keys in hex format or npub format are supported
- Only a subset of relays is used by default
Implementation Details
- Native support for npub format using NIP-19 encoding/decoding
- NIP-57 compliant zap receipt detection with direction-awareness (sent/received/self)
- Advanced bolt11 invoice parsing with payment amount extraction
- Smart caching system for improved performance with large volumes of zaps
- Total sats calculations for sent/received/self zaps with net balance
- Optional NIP-57 validation for ensuring zap receipt integrity
- Anonymous zap support with lightning invoice generation
- Support for zapping profiles, events (note IDs), and replaceable events (naddr)
- Each tool call creates a fresh connection to the relays, ensuring reliable data retrieval
Anonymous Zaps
The sendAnonymousZap
tool lets users send zaps without revealing their Nostr identity. Key points about anonymous zaps:
- The zap will appear to come from an anonymous user in the recipient's wallet
- The zap follows the NIP-57 protocol but without a sender signature
- The recipient can still receive the payment and any included message
- You can zap profiles (using npub/hex pubkey), specific events (using note/nevent/hex ID), or replaceable events (using naddr)
- The server generates a lightning invoice for payment that you can copy into your Lightning wallet
Examples:
The server fully validates LNURL services according to LNURL-pay (LUD-06) and Lightning Address (LUD-16) specifications, ensuring compatibility with various wallet implementations.
Troubleshooting
- If queries time out, try increasing the
QUERY_TIMEOUT
value in the source code (currently 8 seconds) - If no data is found, try specifying different relays that might have the data
- Check Claude's MCP logs for detailed 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 relevant file in the project root:
index.ts
: Main server and tool registrationzap-tools.ts
: Zap-related functionality (getSentZaps, getReceivedZaps, getAllZaps)nips-tools.ts
: NIPs search functionality
- Run
npm run build
to compile - Restart Claude for Desktop or Cursor to pick up your changes
The codebase is organized into modules:
- Core server setup and tools for profiles and notes are in
index.ts
- Zap functionality is encapsulated in
zap-tools.ts
- NIPs search is implemented in
nips-tools.ts
This separation makes the codebase more maintainable and easier to extend with new features.
You must be authenticated.
A Model Context Protocol server that enables LLMs like Claude to interact with the Nostr social network, allowing for fetching user profiles, text notes, and zap payment information.
- Features
- Installation
- Connecting to Claude for Desktop
- Connecting to Cursor
- Usage in Claude
- Advanced Usage
- Limitations
- Implementation Details
- Anonymous Zaps
- Troubleshooting
- Default Relays
- Development