Nostr MCP Server

How to use

You interact with the Nostr MCP server by running it locally or remotely and connecting your MCP client to it. The server exposes a comprehensive set of tools for reading data from Nostr, managing profiles and keys, creating and publishing notes, handling generic events, social actions like following and reacting, direct messaging, anonymous operations, and NIP-19 entity handling. You can call these tools through your MCP client to perform tasks such as fetching profiles, posting notes, encrypting messages, or converting NIP-19 entities.

How to install

Prerequisites: you need a supported Node.js environment and a package manager to install and run the MCP server.

Option 1: Install from npm (recommended)

npm install -g nostr-mcp-server

Option 2: Install from source using Bun (recommended for development)

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

# Install dependencies
bun install

# Build the project
bun run build

Option 3: Install from source using npm

# 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 and other clients

To enable Claude for Desktop to use the MCP server, place the MCP configuration inside Claude’s settings. If you installed via npm, use npx to run the server in your client configuration. If you built from source, reference the absolute path to the built index.js in your client configuration. The configuration anchors the MCP server under the nostr key with the appropriate command and arguments.

Example configurations shown in code blocks below illustrate how to wire the MCP server for both installation methods.

For npm installations, the configuration snippet is:

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

For source installations, the configuration should point to the built index.js file, using the absolute path to the built artifact:

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

Connecting to Cursor and Goose

If you also use Cursor or Goose as your MCP clients, add the same nostr server configuration to their MCP settings. The same npm-based or source-based wiring applies; you simply place the corresponding command and arguments in each client’s configuration and restart the client.

getProfile

Fetches a user profile by public key.

getKind1Notes

Retrieves text notes authored by a user (kind 1).

getLongFormNotes

Retrieves long-form content authored by a user (kind 30023).

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 with direction and totals.

queryEvents

Generic event query tool supporting kinds, authors, ids, tags, and timestamps.

getContactList

Fetches a user's contact list and followed pubkeys.

getFollowing

Alias of getContactList.

getRelayList

Fetches a user's relay list metadata (NIP-65 kind 10002).

createKeypair

Generate new Nostr keypairs in hex and/or npub/nsec format.

createProfile

Create a new Nostr profile (kind 0) with metadata.

updateProfile

Update an existing Nostr profile with new metadata.

createNote

Create unsigned kind 1 note events with content and tags.

signNote

Sign note events with a private key to generate valid signatures.

publishNote

Publish signed notes to specified Nostr relays.

postNote

Authenticated note posting using an existing private key.

createNostrEvent

Create unsigned Nostr events of any kind for low-level building blocks.

signNostrEvent

Sign any unsigned Nostr event with a private key.

publishNostrEvent

Publish any signed Nostr event to relays.

setRelayList

Publish relay list metadata (NIP-65).

follow

Follow a pubkey by updating your contact list.

unfollow

Unfollow a pubkey by updating your contact list.

reactToEvent

React to an event (NIP-7).

repostEvent

Repost an event (NIP-6).

deleteEvent

Delete events via a deletion request (NIP-5).

replyToEvent

Reply to an event with proper NIP-10 threading.

encryptNip04

Encrypt plaintext using NIP-04 for direct messages.

decryptNip04

Decrypt NIP-04 ciphertext for direct messages.

sendDmNip04

Send a NIP-04 encrypted direct message (kind 4).

getDmConversationNip04

Fetch and optionally decrypt a NIP-04 DM conversation.

encryptNip44

Encrypt plaintext using NIP-44 (ChaCha20 + HMAC).

decryptNip44

Decrypt ciphertext using NIP-44 (ChaCha20 + HMAC).

sendDmNip44

Send a NIP-44 encrypted DM using NIP-17 gift wrap (kind 1059).

decryptDmNip44

Decrypt a NIP-17 gift wrapped DM (kind 1059).

getDmInboxNip44

Fetch and decrypt your NIP-44 DM inbox (NIP-17).

sendAnonymousZap

Prepare an anonymous zap and generate a lightning invoice.

postAnonymousNote

Post an anonymous note using a randomly generated one-time keypair.

convertNip19

Convert between NIP-19 entitites (hex, npub, nsec, note, nprofile, nevent, naddr).

analyzeNip19

Analyze and decode any NIP-19 entity to understand its type and contents.

createNote

Create unsigned kind 1 note events with content and tags.

signNote

Sign note events with a private key to generate valid signatures.