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

by kwaude

Overview Schema Source Related Servers Discussions Admin

JavaScript

Remote

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.

Available Tools

6 tools

check_can_messageC

Check if an address can receive XMTP messages

ParametersJSON Schema

Name	Required	Description	Default
`address`	Yes	Wallet address to check

TDQS

C2.9/5.0

Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations provided, the description carries the full burden of behavioral disclosure. It states the tool checks message reception capability but doesn't describe what the check entails (e.g., network calls, permissions, rate limits), the response format, or any side effects. This leaves significant gaps in understanding how the tool behaves.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single, efficient sentence that directly states the tool's purpose without any fluff or redundancy. It is front-loaded and appropriately sized, making it easy to parse quickly.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness2/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a tool with no annotations and no output schema, the description is incomplete. It doesn't explain what the check returns (e.g., boolean, status details), potential error conditions, or how it integrates with sibling tools like 'send_message'. Given the complexity of verifying message reception, more context is needed for effective use.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The input schema has 100% description coverage, with the 'address' parameter clearly documented as a wallet address. The description adds no additional semantic details beyond this, such as address format examples or validation rules. Given the high schema coverage, a baseline score of 3 is appropriate as the schema handles the heavy lifting.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool's purpose with a specific verb ('Check') and resource ('an address can receive XMTP messages'), making it immediately understandable. However, it doesn't explicitly differentiate from sibling tools like 'connect_xmtp' or 'get_messages', which might have overlapping contexts but different functions.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description provides no guidance on when to use this tool versus alternatives, such as whether it should be used before 'send_message' to verify address capability or as a standalone check. There's no mention of prerequisites, exclusions, or recommended contexts, leaving usage unclear.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

connect_xmtpC

Connect to XMTP network with wallet key

ParametersJSON Schema

Name	Required	Description	Default
`privateKey`	No	Wallet private key (optional, uses env WALLET_KEY if not provided)
`environment`	No	XMTP environment: local, dev, or production	production

TDQS

C2.9/5.0

Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations are provided, so the description carries the full burden of behavioral disclosure. It states the tool connects to the XMTP network, implying a setup/initialization operation, but lacks details on authentication needs (e.g., permissions required), side effects (e.g., whether it establishes a persistent session), rate limits, error handling, or what happens on failure. The description is minimal and misses key behavioral traits for a connection tool.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single, efficient sentence with zero waste—it directly states the tool's purpose without fluff or redundancy. It's appropriately sized for a simple connection tool and front-loaded with the core action. Every word earns its place, making it highly concise and well-structured.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness2/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the tool's complexity (a connection operation with authentication), lack of annotations, and no output schema, the description is incomplete. It doesn't cover what the tool returns (e.g., a connection object, status), error cases, dependencies on sibling tools, or behavioral nuances. For a tool that likely enables other messaging functions, more context is needed to guide effective use.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, with both parameters ('privateKey' and 'environment') fully documented in the schema. The description adds no parameter-specific semantics beyond what the schema provides, such as explaining the wallet key format or environment implications. Baseline score is 3 since the schema does the heavy lifting, but the description doesn't compensate or add extra context.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the action ('Connect to XMTP network') and the resource ('XMTP network'), with the method ('with wallet key') specified. It distinguishes this as a connection/initialization tool versus messaging or querying siblings, though it doesn't explicitly name alternatives. The purpose is specific and actionable, but lacks explicit sibling differentiation for a perfect score.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description provides no guidance on when to use this tool versus alternatives, prerequisites, or context. It doesn't mention if this is required before using sibling tools like 'send_message' or 'get_messages', nor does it specify scenarios like initial setup or reconnection. Usage is implied only by the tool's name and basic function, with no explicit when/when-not instructions.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

get_messagesC

Get messages from a conversation with an address

ParametersJSON Schema

Name	Required	Description	Default
`address`	Yes	Wallet address to get conversation with
`limit`	No	Maximum number of messages to retrieve

TDQS

C2.9/5.0

Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations are provided, so the description carries full burden. It states the action ('Get messages') but lacks behavioral details: it doesn't specify if this is a read-only operation, what permissions are needed, how messages are ordered (e.g., chronological), if there's pagination beyond the 'limit' parameter, or what happens if the address has no conversation. For a tool with no annotations, this is a significant gap in transparency.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single, efficient sentence that directly states the tool's purpose without unnecessary words. It's front-loaded with the core action ('Get messages') and includes essential context ('from a conversation with an address'). Every part earns its place, making it highly concise and well-structured.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness2/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given no annotations and no output schema, the description is incomplete for a tool with 2 parameters. It doesn't cover behavioral aspects like safety (read-only vs. mutation), error handling, or return format. For a read operation in a messaging context, more context on ordering, permissions, or response structure would improve completeness.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, with clear descriptions for both parameters ('address' and 'limit'). The description adds minimal value beyond the schema, mentioning 'address' but not elaborating on its format or context. It doesn't explain parameter interactions (e.g., how 'limit' affects retrieval). Baseline 3 is appropriate since the schema does the heavy lifting.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the verb ('Get') and resource ('messages'), specifying the source ('from a conversation with an address'). It distinguishes from siblings like 'send_message' (write vs. read) and 'list_conversations' (messages vs. conversations), but doesn't explicitly differentiate from 'stream_messages' (batch vs. stream). The purpose is specific but could be more precise about sibling differentiation.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description provides no guidance on when to use this tool versus alternatives. It doesn't mention prerequisites (e.g., whether the conversation must exist or be initialized), nor does it compare to siblings like 'stream_messages' for real-time updates or 'list_conversations' for overviews. Usage is implied by the name but not explicitly stated.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

list_conversationsB

List all active XMTP conversations

ParametersJSON Schema

Name	Required	Description	Default
No parameters

TDQS

B3.1/5.0

Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations provided, the description carries full burden for behavioral disclosure. It states this lists 'active' conversations, implying a filter, but doesn't explain what 'active' means, whether this is a read-only operation, how results are returned (e.g., pagination), or any rate limits. This is inadequate for a tool with zero annotation coverage.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single, efficient sentence that directly states the tool's purpose without any wasted words. It's appropriately sized and front-loaded, making it easy for an agent to parse quickly.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness2/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the lack of annotations and output schema, the description is incomplete. It doesn't explain what 'active' entails, the return format, or how this tool relates to siblings like 'get_messages'. For a tool with no structured behavioral data, more context is needed to be fully helpful.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The tool has 0 parameters with 100% schema description coverage, so the schema fully documents the lack of inputs. The description doesn't need to add parameter information, and it correctly doesn't mention any parameters, earning a baseline high score for this dimension.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the verb ('List') and resource ('active XMTP conversations'), making the purpose immediately understandable. However, it doesn't differentiate from sibling tools like 'get_messages' or 'stream_messages', which also deal with conversations/messages, so it doesn't reach the highest clarity level.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description provides no guidance on when to use this tool versus alternatives like 'get_messages' or 'stream_messages'. It doesn't mention prerequisites (e.g., whether 'connect_xmtp' must be called first) or exclusions, leaving the agent to infer usage context.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

send_messageC

Send a message to an address via XMTP

ParametersJSON Schema

Name	Required	Description	Default
`recipient`	Yes	Wallet address or ENS name to send message to
`message`	Yes	Message content to send

TDQS

C2.9/5.0

Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations provided, the description carries full burden for behavioral disclosure. It states the tool sends a message but doesn't cover critical traits like whether it's a write operation, authentication requirements, rate limits, error handling, or what happens on success/failure. This leaves significant gaps for a tool that performs an action.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single, efficient sentence with zero wasted words. It's appropriately sized and front-loaded, directly stating the tool's purpose without unnecessary elaboration.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness2/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a tool that performs a write action (sending a message) with no annotations and no output schema, the description is incomplete. It lacks information on behavioral traits, response format, error conditions, and integration with sibling tools, making it inadequate for safe and effective use.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so the input schema already documents both parameters ('recipient' and 'message') adequately. The description adds no additional parameter semantics beyond what the schema provides, meeting the baseline for high coverage.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the action ('send a message') and target ('to an address via XMTP'), providing a specific verb+resource combination. However, it doesn't explicitly differentiate from sibling tools like 'get_messages' or 'stream_messages', which prevents a perfect score.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description provides no guidance on when to use this tool versus alternatives. It doesn't mention prerequisites (e.g., needing to connect via 'connect_xmtp' first), appropriate contexts, or exclusions, leaving the agent with minimal usage direction.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

stream_messagesC

Start streaming new messages from all conversations

ParametersJSON Schema

Name	Required	Description	Default
`callback`	No	Optional callback function name for message handling

TDQS

C2.9/5.0

Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations provided, the description carries full burden for behavioral disclosure. While 'Start streaming' implies a long-running or real-time operation, it doesn't describe what 'streaming' entails (e.g., continuous data flow, event-driven updates), how to handle the stream, termination conditions, or potential side effects like resource consumption or network usage.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single, efficient sentence that directly states the tool's function without unnecessary words. It's front-loaded with the core action and resource, making it immediately clear what the tool does.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness2/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a streaming tool with no annotations and no output schema, the description is insufficient. It doesn't explain what 'streaming' returns (e.g., real-time message objects, event streams), how to interact with the stream, or important behavioral aspects like error handling or cleanup requirements, leaving significant gaps for agent understanding.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, with the single parameter 'callback' fully documented in the schema. The description adds no additional parameter information beyond what the schema provides, so it meets the baseline for adequate but unremarkable coverage.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the action ('Start streaming') and target resource ('new messages from all conversations'), making the purpose immediately understandable. However, it doesn't differentiate from sibling tools like 'get_messages' (which presumably retrieves existing messages rather than streaming new ones), so it doesn't reach the highest score.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description provides no guidance on when to use this tool versus alternatives like 'get_messages' or 'send_message'. It doesn't mention prerequisites (e.g., whether 'connect_xmtp' must be called first) or appropriate contexts for streaming versus other message operations.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

6 tool updatesAug 23, 2025
- First observedcheck_can_message
- First observedconnect_xmtp
- First observedget_messages
- First observedlist_conversations
- First observedsend_message
- First observedstream_messages

Deploy Server

One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

TDQS

A3.5/5.0

Scored 2026-04-18 08:50 across 6 tools

Disambiguation5/5

Each tool has a clearly distinct purpose with no overlap: checking message capability, connecting to the network, retrieving messages, listing conversations, sending messages, and streaming messages. The descriptions make it easy for an agent to select the right tool for each specific action in the XMTP messaging workflow.

Naming Consistency5/5

All tool names follow a consistent verb_noun pattern using snake_case, such as check_can_message, connect_xmtp, get_messages, list_conversations, send_message, and stream_messages. This uniformity makes the tool set predictable and easy to navigate for an agent.

Tool Count5/5

With 6 tools, this server is well-scoped for handling XMTP messaging operations. Each tool serves a specific and necessary function in the domain, from setup (connect_xmtp) to core messaging actions (send_message, get_messages) and monitoring (stream_messages), without being overly sparse or bloated.

Completeness4/5

The tool set covers essential messaging workflows comprehensively, including connection, sending, receiving, listing conversations, and streaming. A minor gap exists in lacking explicit tools for conversation management (e.g., deleting or archiving conversations), but agents can still perform core operations effectively without major dead ends.

Resources

Need Help?

Reddit Discussion

Related Servers

Related MCP Connectors

WaAPIOAuth
app.waapi
Messaging tools for AI agents: send messages, manage chats, groups and channels.
Communication Workplace & Productivity
1
Agent Commons A
dev.alexlabs
End-to-end encrypted messaging and work coordination for autonomous AI agents.
Autonomous Agents Communication
341
Lettera A
dev.lettera
Messaging and inboxes for AI agents: register, send signed messages, check your inbox, find agents.
Communication Agent Orchestration
71
TokenripOAuth
io.github.silostack
Collaboration layer for AI agents. Publish assets, send messages, manage threads and contacts.
Agent Orchestration Communication
24

Related MCP Servers

Twitter MCP Server
Social Media Communication
taazkareem
A
license
Not graded
quality
D
maintenance
Provides AI agents with comprehensive Twitter functionality through the Model Context Protocol standard, enabling reading tweets, posting content, managing interactions, and accessing timeline data with robust error handling.
Updated 2 years ago (2025-02-14 06:13 UTC)
7 npm
20
MIT
XTBApiServer
Finance Search
sharplygroup
-
license
Not graded
quality
Not graded
maintenance
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.
Updated a year ago (2025-09-26 06:59 UTC)
7 npm
1
-
XTQuantAI
Finance Data Platforms App Automation
dfkai
A
license
B
quality
D
maintenance
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.
Updated 3 months ago (2026-06-11 08:12 UTC)
8
161
MIT
Armor Crypto MCPofficial
Blockchain Cryptocurrency Web3 & Decentralized Tech
armorwallet
A
license
C
quality
C
maintenance
An MCP server providing unified access to blockchain operations, bridging, swapping, and crypto trading strategies for AI agents.
Updated a year ago (2025-07-29 15:53 UTC)
37
179
GPL 3.0

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

Available Tools

Tool Schema Changelog

Resources

Related MCP Connectors

Related MCP Servers

Armor Crypto MCPofficial