You operate an MCP server that exposes a telnet-based BBS bridge, enabling AI agents to interact with vintage BBS systems through the Model Context Protocol. This server provides full terminal emulation, auto-learning of menus and prompts, session logging, and a suite of MCP tools to control, navigate, and analyze BBS interactions from an MCP client.

How to use

Start the MCP server as a stdio transport so your MCP client can connect directly from the same machine or via a flexible inter-process channel. You can run with default settings or specify the host and port to target a remote MCP endpoint. Once running, connect your MCP client to the server, issue commands to connect to a BBS, read screens, send keystrokes, and enable auto-learning to build a navigable knowledge base of menus and prompts.

How to install

Prerequisites: ensure you have a compatible Python runtime and a preferred package manager available on your system.

# Basic prerequisites (example)
python3 --version
python3 -m pip --version

Install the MCP server as a tool via the recommended package manager, or install it using Python's package manager. Then configure your MCP client to connect to the server as shown in the examples.

# Option 1: Install as a tool (recommended)
uv tool install mcp-bbs

# Add to your MCP client configuration as an MCP server

{
  "mcpServers": {
    "mcp_bbs": {
      "command": "mcp-bbs"
    }
  }
}

Option 2: Install with pip

pip install mcp-bbs

Run the server via MCP client configuration that launches the executable

## Additional sections

Configuration and runtime details help tailor the server to your environment. The server supports both local stdio operation and explicit host/port listening configurations. You can enable session logging, adjust the terminal size, and control auto-learning features to populate the knowledge base with menus, prompts, and navigation flows. A variety of MCP tools are exposed for connection management, screen interaction, auto-learning, session management, and keepalive control.

## MCP server configurations

The server can be started in two ways: directly as a stdio transport with a simple command, or with host/port options to listen on a network endpoint. Use the commands shown below.

## 

[ { "type": "stdio", "name": "mcp_bbs", "command": "mcp-bbs", "args": [] }, { "type": "stdio", "name": "mcp_bbs_hosted", "command": "mcp-bbs", "args": ["--host", "localhost", "--port", "2002"] } ]

## Available tools

### bbs\_connect

Connect to a BBS via telnet using the MCP server tools, establishing a session with the target host and port.

### bbs\_disconnect

Gracefully close the BBS connection and terminate the active session.

### bbs\_status

Query the current connection status, session identifier, and recent activity timestamps for RX/TX.

### bbs\_read

Read the current screen state from the BBS, returning a full snapshot including the screen text, cursor position, and raw bytes. This method always logs data for later reference.

### bbs\_read\_until\_nonblank

Continue reading from the BBS until non-whitespace content appears or a timeout occurs.

### bbs\_read\_until\_pattern

Read until the screen matches a specified regular expression pattern, returning a snapshot with a matched flag.

### bbs\_send

Send keystrokes to the BBS using CP437 encoding to navigate menus or respond to prompts.

### bbs\_wake

Attempt multiple keystroke sequences until the screen changes, useful for recovering from idle timeouts.

### bbs\_auto\_learn\_enable

Enable or disable automatic learning of prompts and menus to grow the knowledge base.

### bbs\_auto\_learn\_prompts

Configure rules for auto-detecting prompts and capturing user inputs.

### bbs\_auto\_learn\_menus

Configure rules to auto-detect menu options and their mappings.

### bbs\_auto\_learn\_discover

Enable automatic discovery of option patterns such as [X] style menus.

### bbs\_learn\_menu

Manually document a menu with its options and associated prompts for future automation.

### bbs\_learn\_prompt

Manually document a prompt with its pattern, input type, and example input.

### bbs\_learn\_flow

Document navigation flows between screens to capture user journeys in the knowledge base.

### bbs\_log\_start

Start a JSONL session log to preserve raw data for later reference.

### bbs\_log\_stop

Stop the active session logging.

### bbs\_log\_note

Attach a structured note to the current log for debugging purposes.

### bbs\_set\_context

Attach metadata to all subsequent log entries to provide context.

### bbs\_set\_keepalive

Configure keepalive behavior to prevent idle timeouts, including interval and key sequences.