talk2server 0.1.0

Talk to your SSH servers from Claude and other MCP clients.

Talk2Server

Talk to your SSH servers from Claude and other MCP clients.

Talk2Server is a Model Context Protocol (MCP) server that lets AI assistants run shell commands, read files, and transfer files on remote servers via SSH. It works with Claude Desktop, Claude Code, Cowork, Cursor, Cline, Continue, and any other MCP-compatible client.

You configure your servers once. After that you just talk:

"What's the disk usage on production?" "Show me the last 50 lines of the nginx error log on staging." "Pull /var/log/app/last_run.log from vps to my Desktop."

Why

Managing servers means jumping between terminals, remembering hostnames, typing the same diagnostic commands a hundred times. With Talk2Server, your AI assistant becomes the layer in between. You describe the goal, it runs the commands.

Features

• Multi-host: configure as many servers as you want, address them by alias.
• Three credential backends:
  • OS keychain (macOS Keychain, Windows Credential Manager, Linux Secret Service) for strong, OS-managed storage.
  • Plain JSON file at ~/.config/talk2server/credentials.json (mode 0600), AWS-CLI style.
  • Read-only ~/.ssh/config so power users with existing setups get zero-config support.
• Auto-resolution: if you have a host in ~/.ssh/config, it just works. Otherwise the keychain is checked, then the file.
• Friendly CLI for adding, listing, testing, and migrating credentials.
• Works with any MCP client that speaks stdio.

Install

Talk2Server is published on PyPI. The recommended install uses uv:

# Install uv if you don't have it
curl -LsSf https://astral.sh/uv/install.sh | sh

# Install talk2server as a tool (gets you the `talk2server` CLI)
uv tool install talk2server

Or with pip:

pip install talk2server

Set up your first host

talk2server add

You'll be asked where to store credentials (keychain or file), then prompted for hostname, user, port, auth method, and (if needed) password or key path.

Verify it works:

talk2server test myhost

If you see OK, you're good.

Wire it into Claude Desktop

Edit ~/Library/Application Support/Claude/claude_desktop_config.json (macOS), %APPDATA%\Claude\claude_desktop_config.json (Windows), or the equivalent on Linux. Add this entry under mcpServers:

{
  "mcpServers": {
    "talk2server": {
      "command": "talk2server-mcp"
    }
  }
}

If you installed with uv tool install, that command is already on your PATH. Otherwise point at the absolute path:

{
  "mcpServers": {
    "talk2server": {
      "command": "/Users/you/.local/bin/talk2server-mcp"
    }
  }
}

Restart Claude. You should see talk2server listed in the connectors panel with no warnings.

Wire it into Claude Code

claude mcp add talk2server -- talk2server-mcp

Available tools

The MCP server exposes:

• list_hosts() returns all configured server names with hostname/user/port.
• run_command(host, command, timeout=120) runs a shell command, returns stdout+stderr+exit code.
• upload_file(host, local_path, remote_path) SCP upload.
• download_file(host, remote_path, local_path) SCP download.
• read_remote_file(host, path, max_bytes=200000) cat a remote text file with a size cap.

CLI reference

talk2server add                          # Interactive: add a host
talk2server list                         # Show configured hosts
talk2server list --show-secrets          # Include passwords (use carefully)
talk2server remove <name>                # Delete a host
talk2server test <name>                  # Run a quick SSH connectivity check
talk2server backends                     # Show active backends and write target
talk2server migrate --from file --to keychain

Choosing a backend

Set TALK2SERVER_BACKEND in your MCP client config to pin a backend:

{
  "mcpServers": {
    "talk2server": {
      "command": "talk2server-mcp",
      "env": { "TALK2SERVER_BACKEND": "keychain" }
    }
  }
}

Valid values: auto (default), keychain, file, ssh_config.

In auto mode the read order is: ~/.ssh/config → keychain → file. Writes go to keychain if available, else to the file.

Security

See SECURITY.md for an honest breakdown of what each backend protects against. Short version:

• Keychain binds credentials to your OS user account; malware running as you can still read them, but file copies to other machines are useless.
• File is mode 0600 in your home directory. Equivalent in security to ~/.aws/credentials. Good enough for most workflows, not for high-stakes shared machines.
• ~/.ssh/config stores no passwords; relies entirely on whatever you've already set up (ssh-agent, key files).

License

MIT. See LICENSE.