📜 letters-mcp

An official Model Context Protocol (MCP) server that lets AI clients (Claude Desktop, Cursor, Antigravity, OpenCode) interact directly with Letters to the Future — a decentralized application on Base mainnet where anyone can post time-locked messages into the future or mint them as permanent on-chain SVG NFTs via natural language.

---

🌟 Natural Language Prompt Examples

With this MCP server connected to your AI assistant, you can simply type:

"Post a message for the year 2100: I hope humanity figured out sustainable energy."
"Leave an anonymous note that unlocks in 50 years: we were trying our best."
"Show me the latest 20 letters left by others on Base."
"Mint an on-chain SVG NFT: to whoever finds this — hello from 2026."
"How many letters have been posted so far to date?"

---

📦 Installation & Setup

Option 1: Claude Desktop Integration

Add the following to your Claude Desktop configuration file:

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
• Windows: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "letters": {
      "command": "node",
      "args": ["C:/Users/ad/.gemini/antigravity/scratch/letters-mcp/bin/letters-mcp.js"],
      "env": {
        "PRIVATE_KEY": "0xyour_base_private_key_here"
      }
    }
  }
}

Option 2: Cursor Integration

In Cursor Settings > Features > MCP:

• Name: letters
• Type: command
• Command: node C:/Users/ad/.gemini/antigravity/scratch/letters-mcp/bin/letters-mcp.js

---

🛠️ MCP Tools Reference

Tool	Description	Parameters
post_message	Post an on-chain letter to the future.	content (string, req), unlockYears (number, opt), anonymous (boolean, opt)
list_messages	Fetch recent on-chain letters. Locked ones show unlock date.	limit (number, opt), offset (number, opt)
get_message_count	Query total number of letters posted to date.	None
get_message_by_id	Query a specific message by numerical ID.	id (number, req)
mint_letter_nft	Mint an on-chain SVG Letter NFT (0.001 ETH).	content (string, req)
get_my_nfts	List all Letter NFTs owned by a wallet.	address (string, opt)
get_wallet_info	Check configured agent wallet address and Base ETH balance.	None

---

⛓️ Base Network Contracts

• Network: Base Mainnet (Chain ID: 8453)
• Letters V2 Contract: 0x8FeF460431Ae853fA74fA53f9B005de5cb9Df0EF
• Letter NFT Contract: 0x3C01937B5d7a800C960170F9AF47aBB4237CB6C6
• RPC Endpoints: https://mainnet.base.org, https://base.llamarpc.com

---

⌨️ CLI Usage

# Query total letters on Base
node bin/letters-cli.js count

# Browse recent letters
node bin/letters-cli.js list 10

# Post a letter time-locked for 50 years
node bin/letters-cli.js post "Hello from 2026!" 50 false

# Mint an on-chain SVG Letter NFT (0.001 ETH)
node bin/letters-cli.js mint "A digital time capsule in SVG."

# Launch Interactive Web Studio
npm run studio
# Open http://localhost:3403

---

🔒 Security

Your private key is loaded strictly from the PRIVATE_KEY environment variable and is used only to sign transactions locally via Ethers.js. It is never transmitted anywhere other than directly to the Base RPC endpoint as a signed raw transaction.

---

🚀 How to Publish to GitHub

git init
git add .
git commit -m "feat: initial commit for letters-mcp on Base"
git branch -M main
git remote add origin https://github.com/yappermoar-boop/letters-mcp.git
git push -u origin main

---

📄 License

MIT License. Open source software.