README.md•13.4 kB
# XMTP MCP Server
A Model Context Protocol server that enables AI agents to interact with the XMTP decentralized messaging network.
[](https://www.typescriptlang.org/)
[](https://xmtp.org)
[](https://modelcontextprotocol.io)
## 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:
```bash
# 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**
```bash
# 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:
```bash
# 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
1. **For npm installation**: Create a `.env` file in your working directory:
```bash
# Download example configuration
curl -o .env https://raw.githubusercontent.com/kwaude/xmtp-mcp/main/XMTPMCPServer/.env.example
# Or create manually
touch .env
```
2. **For source installation**: Copy the included template:
```bash
cp .env.example .env
```
3. **Configure your wallet**:
```env
# 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:
1. Visit [xmtp.chat](https://xmtp.chat) or use Coinbase Wallet
2. Import your wallet using the private key from your `.env` file
3. Send a test message to activate your XMTP identity
4. 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:
```bash
# 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
```bash
# 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
```bash
# If installed as project dependency
claude mcp add xmtp node ./node_modules/@kwaude/xmtp-mcp-server/dist/index.js
```
#### From Source Build
```bash
# If building from source
claude mcp add xmtp node /path/to/xmtp-mcp/dist/index.js
```
### Manual Configuration (claude.json)
```json
{
"mcpServers": {
"xmtp": {
"command": "xmtp-mcp-server",
"env": {
"WALLET_KEY": "0x...your_private_key_here",
"XMTP_ENV": "production"
}
}
}
}
```
**Alternative with Node.js**:
```json
{
"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
```javascript
// 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
```bash
# 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
```bash
# Clean previous builds
npm run clean
# Build TypeScript to JavaScript
npm run build
# Start production server
npm start
```
### Development Workflow
1. **Make changes** in `src/index.ts`
2. **Test locally** with `npm run dev`
3. **Build** with `npm run build`
4. **Test build** with `npm start`
5. **Update Claude MCP** if needed:
```bash
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
```bash
# 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
```bash
# 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 `dev` network environment
- Use `environment` parameter in `connect_xmtp` to specify network:
- Production network: `environment: "production"`
- Development network: `environment: "dev"` (default)
### Wallet Activation
**Critical**: Fresh wallets must be activated on the XMTP network before they can send messages:
1. **Network-Specific Activation**: Wallets can connect to any network but need separate activation per network
2. **Activation Process**:
- Connect to [xmtp.chat](https://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 `dev` network
- ✅ **Signer Interface**: Fixed `getChainId()` to return `bigint` instead of `number`
- ✅ **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](https://xmtp.chat)
## Troubleshooting
### Installation Issues
#### Package not found on npm
```bash
# 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
```bash
# 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
```bash
# 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
```bash
# 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
```bash
# 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
```bash
# 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
1. **Activate wallet** via [xmtp.chat](https://xmtp.chat)
2. **Send test message** to establish XMTP identity
3. **Use development wallets** from `.env.development` for testing
#### MCP server not connecting to Claude
```bash
# 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
```bash
# Clean and rebuild
npm run clean
npm install
npm run build
```
#### Module not found errors
```bash
# 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
1. **Check existing issues**: [GitHub Issues](https://github.com/kwaude/xmtp-mcp/issues)
2. **Create new issue**: Provide error logs and environment details
3. **Discord support**: Join [XMTP Discord](https://discord.gg/xmtp) for community help
## Contributing
1. Fork the repository
2. Create a feature branch (`git checkout -b feature/amazing-feature`)
3. Commit your changes (`git commit -m 'Add amazing feature'`)
4. Push to the branch (`git push origin feature/amazing-feature`)
5. Open a Pull Request
## License
This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.
## Links
- [XMTP Documentation](https://docs.xmtp.org/)
- [Model Context Protocol](https://modelcontextprotocol.io/)
- [Claude Code](https://claude.ai/code)