Skip to main content
Glama

XMTP MCP Server

by kwaude
npmGitHub
JavaScript
MIT License
4
1
OverviewInspectNewEndpointsSchemaRelated ServersReviewsScore
Need Help?View Source CodeReport Issue

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

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

  1. 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
  1. For source installation: Copy the included template:
cp .env.example .env
  1. 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:

  1. Visit 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

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

ToolDescriptionParameters
connect_xmtpConnect to XMTP networkprivateKey?, environment?
send_messageSend message to addressrecipient, message
get_messagesGet conversation messagesaddress, limit?
list_conversationsList all conversationsnone
check_can_messageCheck if address can receive messagesaddress
stream_messagesStream new messages in real-timecallback?

Resources

ResourceDescription
xmtp://conversationsJSON list of all conversations
xmtp://inboxJSON 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

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

ScriptPurposeCommand
buildCompile TypeScripttsc
devDevelopment servertsx --env-file .env src/index.ts
startProduction servernode dist/index.js
cleanRemove build artifactsrm -rf dist
lintCode quality checkeslint src --ext .ts
formatCode formattingprettier --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

EnvironmentDescriptionURL
productionXMTP Mainnetgrpc.production.xmtp.network:443
devXMTP Testnetgrpc.dev.xmtp.network:443
localLocal Developmentlocalhost: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 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
  1. Activate wallet via 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
# 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

  1. Check existing issues: GitHub Issues
  2. Create new issue: Provide error logs and environment details
  3. Discord support: Join XMTP Discord 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 file for details.

Deploy Server
-
security - not tested
A
license - permissive license
-
quality - not tested

How are these scores calculated?

remote-capable server

The server can be hosted and run remotely because it primarily relies on remote services or has no dependency on the local environment.

Tools

Enables AI agents to interact with the XMTP decentralized messaging network. Supports sending encrypted messages, managing conversations, and streaming real-time messages to any XMTP-enabled wallet address.

  1. Features
    1. Installation
      1. Option 1: NPM Package (Recommended)
      2. Option 2: From Source (Development)
    2. Configuration
      1. Environment Setup
      2. Wallet Activation
    3. Claude Code Integration
      1. Quick Setup (Recommended)
      2. Alternative Setup Methods
      3. Manual Configuration (claude.json)
    4. API Reference
      1. Tools
      2. Resources
    5. Examples
      1. Basic Usage
      2. Error Handling
    6. Development
      1. Development Setup
      2. Build Process
      3. Development Workflow
      4. Project Structure
      5. Build Scripts
      6. Testing Locally
      7. Publishing Updates
    7. Security
      1. Requirements
        1. Network Support
          1. Network Configuration
            1. Default Environment
            2. Wallet Activation
          2. Known Issues
            1. canMessage API & Wallet Activation
          3. Troubleshooting
            1. Installation Issues
            2. Configuration Issues
            3. Connection Issues
            4. Development Issues
            5. Getting Help
          4. Contributing
            1. License
              1. Links

                Related MCP Servers

                • XTBApiServer

                  sharplygroup
                  -
                  security
                  F
                  license
                  -
                  quality
                  An MCP server that exposes the XTB trading API, allowing users to interact with their XTB trading accounts through the Model Context Protocol to perform operations like account management, market data retrieval, and trade execution.
                  Last updated -
                  1
                  1

                • XTQuantAI

                  dfkai
                  A
                  security
                  A
                  license
                  A
                  quality
                  An MCP server that integrates the XTQuant quantitative trading platform with AI assistants, allowing AI to directly access and operate on trading data and functionality.
                  Last updated -
                  8
                  91
                  MIT License
                  • Apple

                • YaVendió Toolsofficial

                  YaVendio
                  -
                  security
                  -
                  license
                  -
                  quality
                  An MCP-based messaging system that allows AI systems to interact with various messaging platforms through standardized tools for sending text, images, documents, buttons, and alerts.
                  Last updated -

                • Armor Crypto MCPofficial

                  armorwallet
                  A
                  security
                  A
                  license
                  A
                  quality
                  An MCP server providing unified access to blockchain operations, bridging, swapping, and crypto trading strategies for AI agents.
                  Last updated -
                  37
                  190
                  GPL 3.0
                  • Apple
                  • Linux

                View all related MCP servers

                New MCP Servers

                MCP directory API

                We provide all the information about MCP servers via our MCP API.

                curl -X GET 'https://glama.ai/api/mcp/v1/servers/kwaude/xmtp-mcp'

                If you have feedback or need assistance with the MCP directory API, please join our Discord server