tlon

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

Installation

Run this command in your terminal to add the MCP server to Claude Code.

Run in terminal:

Command

claude mcp add --transport stdio jamesacklin-tlon-mcp-server node index.js \
  --env PORT="MCP server port (HTTP mode only)" \
  --env URBIT_CODE="Your Urbit +code" \
  --env URBIT_HOST="Urbit host" \
  --env URBIT_PORT="Urbit port" \
  --env URBIT_SHIP="Your Urbit ship name (without ~)" \
  --env MCP_TRANSPORT="Transport type (http or stdio)"

How to use

This MCP server provides a set of tools to interact with Tlon agents via the Model Context Protocol. The available tools include send-dm for sending direct messages to other ships, read-dm-history to fetch recent messages from a DM channel, and list-contacts to retrieve your contacts with their nicknames and ship IDs. The server also supports natural language cues, allowing you to reference people by nickname in commands like “Send a message to Brian.” After starting the server, you can use Claude Desktop or another MCP client to issue tool commands in plain English or structured queries, depending on your client’s capabilities.

How to install

Prerequisites:

Node.js 16+ installed on your machine
A running Urbit ship accessible from the host

Installation steps:

Clone the repository:

git clone <repository-url>
cd tlon-mcp-server

Install dependencies:

npm install

Configure environment variables (see Configuration section for details) and start the server:

# Example (bash)
export URBIT_SHIP=<your-ship>
export URBIT_CODE=<your-code>
export URBIT_HOST=localhost
export URBIT_PORT=8080
export PORT=3001
export MCP_TRANSPORT=stdio
npm start

Optional: for Claude Desktop integration, ensure you run npm install in the server directory before configuring Claude Desktop.

Additional notes

Tips and notes:

Ensure your Urbit ship is reachable from the host running the MCP server (proper host/port configured).
If you change MCP_TRANSPORT to http, the server will listen over HTTP on the specified PORT.
When using Claude Desktop, the example Claude config requires you to install dependencies first in the server directory.
The tools support nickname references in addition to ship IDs, so you can say things like “Send a message to Brian” if Brian is a known contact.
Default DM history fetch limits are configurable per tool (e.g., count up to 500). Use the format option to control output formatting.
If you encounter issues with npm install output interfering with the MCP protocol, follow the guidance in the README to run npm install manually before connecting clients.

Related MCP Servers

zen

1.1k

Selfhosted notes app. Single golang binary, notes stored as markdown within SQLite, full-text search, very low resource usage

MCP -Deepseek_R1

A Model Context Protocol (MCP) server implementation connecting Claude Desktop with DeepSeek's language models (R1/V3)

mcp-fhir

A Model Context Protocol implementation for FHIR

mcp

Inkdrop Model Context Protocol Server

mcp-appium-gestures

This is a Model Context Protocol (MCP) server providing resources and tools for Appium mobile gestures using Actions API..

dubco -npm

The (Unofficial) dubco-mcp-server enables AI assistants to manage Dub.co short links via the Model Context Protocol. It provides three MCP tools: create_link for generating new short URLs, update_link for modifying existing links, and delete_link for removing short links.