What can you do with this server?

The XMTP MCP Server enables AI agents to interact with the XMTP decentralized messaging network for secure, real-time communication. * Connect to XMTP Network: Initialize secure connection using wallet private key across production, development, or local environments * Send Encrypted Messages: Dispatch secure messages to any XMTP-enabled wallet address or ENS name * Retrieve Message History: Fetch past conversation messages with customizable limits * Manage Conversations: List and manage all active conversations * Real-time Message Streaming: Stream incoming messages across all conversations as they arrive * Address Validation: Verify if wallet addresses can receive XMTP messages

How do I use XMTP MCP Server?

1. Click on "Install Server". 2. Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state. 3. In the chat, type @ followed by the MCP server name and your instructions, e.g., "@XMTP MCP Server send a message to 0x742d35Cc6634C0532925a3b8D4b9f saying 'Meeting at 2pm tomorrow'" That's it! The server will respond to your query, and you can continue using it as needed. Here is a step-by-step guide with screenshots.

XMTP MCP Server

A Model Context Protocol server that enables AI agents to interact with the XMTP decentralized messaging network.

TypeScript XMTP MCP

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

Related MCP server: XTBApiServer

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 .env file 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 .env file
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 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:

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 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

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.development for 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.

XMTP MCP Server

Features

Installation

Option 1: NPM Package (Recommended)

Option 2: From Source (Development)

Configuration

Environment Setup

Wallet Activation

Claude Code Integration

Quick Setup (Recommended)

Alternative Setup Methods

With Environment Variables

Using Local npm Installation

From Source Build

Manual Configuration (claude.json)

API Reference

Tools

Resources

Examples

Basic Usage

Error Handling

Development

Development Setup

Build Process

Development Workflow

Project Structure

Build Scripts

Testing Locally

Publishing Updates

Security

Requirements

Network Support

Network Configuration

Default Environment

Wallet Activation

Known Issues

canMessage API & Wallet Activation

Troubleshooting

Installation Issues

Package not found on npm

Permission errors during global install

Command not found after global install

CLI shows server output instead of version

Configuration Issues

Environment file not found

Invalid private key format

Connection Issues

XMTP connection failed

Address not on XMTP network

MCP server not connecting to Claude

Development Issues

TypeScript compilation errors

Module not found errors

Getting Help

Contributing

License

Links

Resources

Tools

Latest Blog Posts

MCP directory API