XMTP MCP Server
A Model Context Protocol server that enables AI agents to interact with the XMTP decentralized messaging network.
Features
- 🔐 Secure Connection: Initialize XMTP client with wallet authentication
- 📨 Send Messages: Send encrypted messages to any XMTP-enabled wallet address
- 📬 Receive Messages: Retrieve message history from conversations
- 💬 Conversation Management: List and manage conversations
- 🔄 Real-time Streaming: Stream new messages as they arrive
- ✅ Address Validation: Check if addresses can receive XMTP messages
Installation
Option 1: NPM Package (Recommended)
The easiest way to use the XMTP MCP Server is via npm:
# Install globally to use as CLI tool
npm install -g @kwaude/xmtp-mcp-server
# Verify installation (shows server info)
which xmtp-mcp-server
Alternative: Local Project Installation
# Install as project dependency
npm install @kwaude/xmtp-mcp-server
# Use via npx
npx @kwaude/xmtp-mcp-server
Option 2: From Source (Development)
For development or customization:
# Clone repository
git clone https://github.com/kwaude/xmtp-mcp.git
cd xmtp-mcp
# Install dependencies
npm install
# Build the project
npm run build
# Run locally
npm start
Configuration
Environment Setup
- For npm installation: Create a
.envfile in your working directory:
# Download example configuration
curl -o .env https://raw.githubusercontent.com/kwaude/xmtp-mcp/main/XMTPMCPServer/.env.example
# Or create manually
touch .env
- For source installation: Copy the included template:
cp .env.example .env
- Configure your wallet:
# Required: Your wallet private key
WALLET_KEY=0x...your_private_key_here
# Required: XMTP network environment
XMTP_ENV=production # options: production, dev, local
# Optional: Database encryption key (auto-generated if not set)
ENCRYPTION_KEY=your_32_character_encryption_key_here
Wallet Activation
⚠️ Important: Before using the MCP server, wallets must be activated on XMTP:
- Visit xmtp.chat or use Coinbase Wallet
- Import your wallet using the private key from your
.envfile - Send a test message to activate your XMTP identity
- The wallet is now ready for use with the MCP server
Development Wallets: Use the pre-activated test wallets in .env.development for immediate testing.
Claude Code Integration
Quick Setup (Recommended)
After installing the npm package globally:
# Add XMTP MCP server to Claude Code
claude mcp add xmtp xmtp-mcp-server
# Verify it's working
claude mcp list
Note: Make sure you have a .env file in your current directory with your wallet configuration.
Alternative Setup Methods
With Environment Variables
# Pass environment variables directly
claude mcp add xmtp xmtp-mcp-server \
--env WALLET_KEY=0x...your_key_here \
--env XMTP_ENV=production
Using Local npm Installation
# If installed as project dependency
claude mcp add xmtp node ./node_modules/@kwaude/xmtp-mcp-server/dist/index.js
From Source Build
# If building from source
claude mcp add xmtp node /path/to/xmtp-mcp/dist/index.js
Manual Configuration (claude.json)
{
"mcpServers": {
"xmtp": {
"command": "xmtp-mcp-server",
"env": {
"WALLET_KEY": "0x...your_private_key_here",
"XMTP_ENV": "production"
}
}
}
}
Alternative with Node.js:
{
"mcpServers": {
"xmtp": {
"command": "node",
"args": ["/path/to/dist/index.js"],
"env": {
"WALLET_KEY": "0x...your_private_key_here",
"XMTP_ENV": "production"
}
}
}
}
API Reference
Tools
| Tool | Description | Parameters |
|---|---|---|
connect_xmtp | Connect to XMTP network | privateKey?, environment? |
send_message | Send message to address | recipient, message |
get_messages | Get conversation messages | address, limit? |
list_conversations | List all conversations | none |
check_can_message | Check if address can receive messages | address |
stream_messages | Stream new messages in real-time | callback? |
Resources
| Resource | Description |
|---|---|
xmtp://conversations | JSON list of all conversations |
xmtp://inbox | JSON list of recent inbox messages |
Examples
Basic Usage
// Connect to XMTP
await connectXMTP({
privateKey: "0x...",
environment: "production"
});
// Send a message
await sendMessage({
recipient: "0x742d35Cc6634C0532925a3b8D4b9f22692d06711",
message: "Hello from XMTP MCP Server!"
});
// Check if address can receive messages
const canMessage = await checkCanMessage({
address: "0x742d35Cc6634C0532925a3b8D4b9f22692d06711"
});
Error Handling
The server includes comprehensive error handling:
- Connection failures
- Invalid addresses
- Network timeouts
- Malformed requests
Development
Development Setup
# Clone and setup
git clone https://github.com/kwaude/xmtp-mcp.git
cd xmtp-mcp
# Install dependencies
npm install
# Copy development environment
cp .env.development .env
# Start development server with auto-reload
npm run dev
Build Process
# Clean previous builds
npm run clean
# Build TypeScript to JavaScript
npm run build
# Start production server
npm start
Development Workflow
- Make changes in
src/index.ts - Test locally with
npm run dev - Build with
npm run build - Test build with
npm start - Update Claude MCP if needed:
claude mcp remove xmtp claude mcp add xmtp node ./dist/index.js
Project Structure
xmtp-mcp/
├── src/
│ └── index.ts # Main MCP server implementation
├── dist/ # Compiled JavaScript output
│ ├── index.js # Main entry point
│ ├── index.d.ts # TypeScript declarations
│ └── *.map # Source maps
├── package.json # Package configuration & scripts
├── tsconfig.json # TypeScript compiler config
├── .env.example # Environment template
├── .env.development # Pre-configured test wallets
├── .npmignore # NPM publish exclusions
├── LICENSE # MIT license
└── README.md # Documentation
Build Scripts
| Script | Purpose | Command |
|---|---|---|
build | Compile TypeScript | tsc |
dev | Development server | tsx --env-file .env src/index.ts |
start | Production server | node dist/index.js |
clean | Remove build artifacts | rm -rf dist |
lint | Code quality check | eslint src --ext .ts |
format | Code formatting | prettier --write src/**/*.ts |
Testing Locally
# Test the built package
npm pack
npm install -g ./kwaude-xmtp-mcp-server-*.tgz
# Test CLI command (shows server info)
which xmtp-mcp-server
# Test with Claude Code
claude mcp add test-xmtp xmtp-mcp-server
claude mcp list
Publishing Updates
# Update version in package.json
npm version patch # or minor, major
# Build and publish
npm run build
npm publish
# Push to GitHub
git push --follow-tags
Security
- ✅ Private keys stored in environment variables only
- ✅ End-to-end encrypted messages via XMTP protocol
- ✅ No sensitive data logged or persisted locally
- ✅ Proper input validation and sanitization
Requirements
- Node.js: 20+
- XMTP Network: Active internet connection
- Wallet: Private key for XMTP-compatible wallet
Network Support
| Environment | Description | URL |
|---|---|---|
production | XMTP Mainnet | grpc.production.xmtp.network:443 |
dev | XMTP Testnet | grpc.dev.xmtp.network:443 |
local | Local Development | localhost:5556 |
Network Configuration
Default Environment
- Important: XMTP client defaults to
devnetwork environment - Use
environmentparameter inconnect_xmtpto specify network:- Production network:
environment: "production" - Development network:
environment: "dev"(default)
- Production network:
Wallet Activation
Critical: Fresh wallets must be activated on the XMTP network before they can send messages:
- Network-Specific Activation: Wallets can connect to any network but need separate activation per network
- Activation Process:
- Connect to xmtp.chat with your wallet
- Send a message on the desired network (dev or production)
- This establishes your XMTP identity on that specific network
Testing: Use pre-activated wallets from .env.development for immediate development.
Known Issues
canMessage API & Wallet Activation
Status: 🐛 Active Issue - Resolved ✅
Root Cause: Wallets need proper activation on each XMTP network.
Investigation Results:
- ✅ Default Network: Confirmed XMTP defaults to
devnetwork - ✅ Signer Interface: Fixed
getChainId()to returnbigintinstead ofnumber - ✅ Case Sensitivity: Implemented fallback for address case variations
- ⚠️ Wallet Activation: Test wallets require activation via xmtp.chat
Fixed Issues:
- Connection interface properly implemented
- Case sensitivity handling in canMessage checks
- Network environment configuration corrected
Remaining Action: Activate test wallets on desired network via xmtp.chat
Troubleshooting
Installation Issues
Package not found on npm
# Check if package is available
npm view @kwaude/xmtp-mcp-server
# If not available, install from GitHub
npm install -g https://github.com/kwaude/xmtp-mcp.git#main
Permission errors during global install
# Use npm prefix to install to user directory
npm install -g @kwaude/xmtp-mcp-server --prefix ~/.npm-global
# Or use npx without global install
npx @kwaude/xmtp-mcp-server
Command not found after global install
# Check installation path
npm list -g @kwaude/xmtp-mcp-server
# Check PATH includes npm global bin
echo $PATH | grep npm
# Add to PATH if missing (add to ~/.bashrc or ~/.zshrc)
export PATH="$PATH:$(npm config get prefix)/bin"
# Verify command is available
which xmtp-mcp-server
CLI shows server output instead of version
This is expected behavior. The xmtp-mcp-server command starts the MCP server immediately and communicates via stdio. Use which xmtp-mcp-server or npm list -g @kwaude/xmtp-mcp-server to verify installation.
Configuration Issues
Environment file not found
# Create .env file in current directory
touch .env
# Download example configuration
curl -o .env https://raw.githubusercontent.com/kwaude/xmtp-mcp/main/XMTPMCPServer/.env.example
Invalid private key format
# Ensure private key starts with 0x
WALLET_KEY=0x1234567890abcdef...
# Check key length (should be 66 characters including 0x)
echo ${#WALLET_KEY} # Should output: 66
Connection Issues
XMTP connection failed
# Check network environment
XMTP_ENV=production # Try: dev, production, local
# Verify wallet key is valid
node -e "console.log(require('ethers').Wallet.fromPrivateKey('$WALLET_KEY').address)"
Address not on XMTP network
- Activate wallet via xmtp.chat
- Send test message to establish XMTP identity
- Use development wallets from
.env.developmentfor testing
MCP server not connecting to Claude
# Check MCP server status
claude mcp list
# Restart MCP server
claude mcp remove xmtp
claude mcp add xmtp xmtp-mcp-server
# Check logs for errors
claude mcp logs xmtp
Development Issues
TypeScript compilation errors
# Clean and rebuild
npm run clean
npm install
npm run build
Module not found errors
# Verify all dependencies are installed
npm install
# Check Node.js version (requires 20+)
node --version
# Clear npm cache if needed
npm cache clean --force
Getting Help
- Check existing issues: GitHub Issues
- Create new issue: Provide error logs and environment details
- Discord support: Join XMTP Discord for community help
Contributing
- Fork the repository
- Create a feature branch (
git checkout -b feature/amazing-feature) - Commit your changes (
git commit -m 'Add amazing feature') - Push to the branch (
git push origin feature/amazing-feature) - Open a Pull Request
License
This project is licensed under the MIT License - see the LICENSE file for details.