📜 letters-mcp

License: MIT Network: Base Mainnet Standard: Model Context Protocol

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.

letters-mcp