Metadata-Version: 2.4
Name: talk2server
Version: 0.1.0
Summary: Talk to your SSH servers from Claude and other MCP clients.
Author-email: D <translatee.io.app@gmail.com>
Maintainer-email: D <translatee.io.app@gmail.com>
License: MIT
License-File: LICENSE
Keywords: ai,claude,claude-code,claude-desktop,cowork,devops,mcp,model-context-protocol,server-management,ssh
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: System Administrators
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: MacOS
Classifier: Operating System :: Microsoft :: Windows
Classifier: Operating System :: POSIX :: Linux
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: System :: Systems Administration
Classifier: Topic :: Utilities
Requires-Python: >=3.10
Requires-Dist: click>=8.1
Requires-Dist: keyring>=24.0
Requires-Dist: mcp[cli]>=1.0.0
Provides-Extra: dev
Requires-Dist: pytest-cov>=4.0; extra == 'dev'
Requires-Dist: pytest>=7.0; extra == 'dev'
Requires-Dist: ruff>=0.4; extra == 'dev'
Description-Content-Type: text/markdown

# 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`:

```bash
# 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:

```bash
pip install talk2server
```

## Set up your first host

```bash
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:

```bash
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`:

```json
{
  "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:

```json
{
  "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

```bash
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:

```json
{
  "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](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](LICENSE).
