Tlon Urbit Messenger

🚀 Tlon MCP Server

An MCP (Model Context Protocol) server that provides tools for interacting with Tlon agents.

🚀 Quick Start

Demo

https://github.com/user-attachments/assets/765847b2-df40-44c0-bfd3-c23eb609bbd8

✨ Features

• send-dm tool: Send direct messages to other users by ship ID or nickname.
• read-dm-history tool: Retrieve recent messages from a direct message channel.
• list-contacts tool: Get contacts along with their nicknames and ship IDs.
• Natural language support: Refer to people by nickname (e.g., "Send a message to Brian").

📦 Installation

Prerequisites

• Node.js (v16+)
• A running Urbit ship

Steps

1. Clone the repository.
2. Navigate to the project directory.
3. Install dependencies:

npm install

⚠️ Important Note

Always run npm install manually in the terminal to prevent installation output from interfering with the MCP protocol.

Configuration

Configure the server using environment variables:

💻 Usage Examples

Starting the Server

# Start with the default stdio transport
npm start

# Start with HTTP transport
export MCP_TRANSPORT=http && npm start

# Auto-reload in development mode
npm run dev

Configuring for Use with Claude Desktop

The default stdio mode integrates seamlessly with Claude Desktop. Create or edit the file located at:

~/Library/Application Support/Claude/claude_desktop_config.json

with the following content:

{
  "mcpServers": {
    "tlon-mcp": {
      "command": "/bin/sh",
      "args": ["-c", "cd /path/to/server && node index.js"]
    }
  }
}

⚠️ Important Note

Make sure to run npm install in the server directory before configuring Claude Desktop.

Using Tools with Natural Language Support

Once configured, you can use natural language commands:

Send a message to Brian

Show me the last 50 DM history with ~sampel-palnet

Who are my contacts?

Available Tools

send-dm

Send a direct message to another ship. Parameters:

• recipient: The recipient's ship name (with ~) or nickname.
• message: The content of the message to send. Example command:

node send-dm.js --recipient user@example.com --message "Hello, Tlon!"

read-dm-history

Retrieve recent messages from a direct message channel. Parameters:

• channelId: The ID of the target channel.
• limit: The maximum number of messages to retrieve (optional, default is 10). Example command:

node read-dm-history.js --channelId 12345 --limit 20

list-contacts

Get all contacts and their details. Parameters: None Example command:

node list-contacts.js

📄 License

MIT