Nostr MCP Server for Claude Integration

Overview

The Nostr MCP Server is a Model Context Protocol (MCP) server that enables Nostr capabilities for large language models (LLMs) like Claude. It provides tools for interacting with the Nostr network, allowing users to fetch profiles, notes, and zaps directly through Claude.

Features

The server implements six 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.

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

Installation

To install the Nostr MCP Server:

# 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. Ensure you have Claude for Desktop installed and updated.
2. Configure Claude for Desktop by editing or creating the configuration file:
3. For macOS:
   shell vim ~/Library/Application\ Support/Claude/claude_desktop_config.json
4. For Windows:
   shell notepad %AppData%\Claude\claude_desktop_config.json
5. Add the Nostr server to your configuration:
   json { "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.
6. Restart Claude for Desktop.

Usage in Claude

Once configured, you can ask Claude to use the Nostr tools with 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"

Advanced Usage

• Specify custom relays for any query:
• "Show me the profile for npub1qny3tkh0acurzla8x3zy4nhrjz5zd8ne6dvrjehx9n9hr3lnj08qwuzwc8 using relay wss://relay.damus.io"
• Specify the number of notes or zaps to fetch:
• "Show me the latest 20 notes from npub1qny3tkh0acurzla8x3zy4nhrjz5zd8ne6dvrjehx9n9hr3lnj08qwuzwc8"
• Enable extra validation and debugging for zap queries:
• "Show me all zaps for npub1qny3tkh0acurzla8x3zy4nhrjz5zd8ne6dvrjehx9n9hr3lnj08qwuzwc8 with validation and debug enabled"

Limitations

• Default 8-second timeout for queries.
• 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.
• Each tool call creates a fresh connection to the relays, ensuring reliable data retrieval.

Troubleshooting

• Increase the QUERY_TIMEOUT value in the source code if queries time out.
• Specify different relays if no data is found.
• 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:
1. Edit the index.ts file in the project root.
2. Run npm run build to compile.
3. Restart Claude for Desktop to pick up your changes.

About

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

Topics

• mcp
• nostr

Resources

• Readme

License

• MIT license

Stars

• 20 stars

Watchers

• 1 watching

Forks

• 5 forks

Languages

• JavaScript 100.0%