MCP Server
Connect AI assistants to your servers via the Model Context Protocol. 19 tools for SSH, SFTP, host management, snippets and password vault.
Quick Start
The MCP server is included with the Shellcat desktop app. No separate installation or build needed.
1. Install Shellcat
Download and install the Shellcat desktop app. The MCP binary (shellcat-mcp) is bundled automatically.
2. Find the binary path
The shellcat-mcp binary is located inside the app bundle. The path depends on your operating system:
# macOS
/Applications/Shellcat.app/Contents/MacOS/shellcat-mcp
# Windows
C:\Program Files\Shellcat\shellcat-mcp.exe
# Linux
/usr/bin/shellcat-mcp3. Configure your MCP client
Add the shellcat server to your MCP client config. For Claude Desktop, edit claude_desktop_config.json:
// macOS
{
"mcpServers": {
"shellcat": {
"command": "/Applications/Shellcat.app/Contents/MacOS/shellcat-mcp"
}
}
}
// Windows
{
"mcpServers": {
"shellcat": {
"command": "C:\\Program Files\\Shellcat\\shellcat-mcp.exe"
}
}
}4. Start using it
Restart your MCP client. Shellcat tools will appear automatically. The server uses your local Shellcat database — the same hosts, keys, snippets and vault you see in the desktop app.
Tools Reference
All 19 tools available through the MCP server. Hosts and snippets can be referenced by ID or label.
SSH
ssh_executeExecute a command on a remote server via SSH. Returns stdout, stderr and exit code.
hostrequiredHost ID or labelcommandrequiredShell command to executeSFTP
sftp_listList files and directories at a path on a remote server.
hostrequiredHost ID or labelpathrequiredRemote pathsftp_readmax 1MBRead the contents of a text file on a remote server.
hostrequiredHost ID or labelpathrequiredRemote file pathsftp_writeWrite content to a file on a remote server.
hostrequiredHost ID or labelpathrequiredRemote file pathcontentrequiredFile content to writesftp_mkdirCreate a directory (and parents) on a remote server.
hostrequiredHost ID or labelpathrequiredRemote directory pathsftp_deleteDelete a file or empty directory on a remote server.
hostrequiredHost ID or labelpathrequiredRemote pathHosts
host_listList all saved SSH hosts with connection details.
host_createAdd a new SSH host to the saved hosts list.
labelrequiredDisplay namehostnamerequiredServer hostname or IPusernamerequiredSSH usernameportSSH port (default: 22)auth_methodpassword or keygroupHost group namehost_deleteDelete a saved SSH host.
hostrequiredHost ID or labelSnippets
snippet_listList all saved command snippets.
snippet_createCreate a new command snippet.
labelrequiredDisplay namecommandrequiredShell command to executedescriptionDescription (optional)snippet_deleteDelete a saved snippet.
snippetrequiredSnippet ID or labelsnippet_executeExecute a saved snippet on a remote host via SSH.
snippetrequiredSnippet ID or labelhostrequiredHost ID or labelPassword Vault
vault_statusCheck if the vault is unlocked and if a master password has been set up.
vault_unlockUnlock the vault with the master password.
master_passwordrequiredMaster passwordvault_listList vault entries (titles, usernames, URLs). Passwords are not returned.
categoryFilter by categoryvault_getGet a vault entry with decrypted password (requires unlock).
entryrequiredEntry ID or titlevault_createCreate a new vault entry. Password and notes are encrypted.
titlerequiredEntry titleusernamerequiredSSH usernamepasswordrequiredPassword to storeurlWebsite URLcategoryFilter by categoryvault_deleteDelete a vault entry.
entryrequiredEntry ID or titleAuthentication
The vault and encrypted host passwords require the master password to be unlocked first. Use vault_unlock at the start of a session, then all tools will have access to decrypted data.
// First, unlock the vault
→ vault_unlock({ master_password: "..." })
// Verify it worked
→ vault_status()
{ "setup": true, "unlocked": true }Examples
Check server logs
user: Show me the last errors from the prod-api server
agent:
→ host_list()
→ ssh_execute({ host: "prod-api", command: "tail -20 /var/log/app/error.log" })
Found 3 errors in the last hour — all slow DB queries on the orders table.Edit a remote config
user: Update the nginx config on web-server to increase worker_connections to 2048
agent:
→ sftp_read({ host: "web-server", path: "/etc/nginx/nginx.conf" })
→ sftp_write({ host: "web-server", path: "/etc/nginx/nginx.conf", content: "..." })
→ ssh_execute({ host: "web-server", command: "nginx -t && systemctl reload nginx" })
Config updated and nginx reloaded. Syntax check passed.Look up a password
user: What are the AWS production credentials?
agent:
→ vault_unlock({ master_password: "..." })
→ vault_get({ entry: "AWS Production" })
AWS Production — access key: AKIA..., secret: (returned securely)Compatible Clients
Shellcat MCP works with any client that supports the MCP stdio transport:
Protocol
Shellcat MCP uses JSON-RPC 2.0 over stdio, following the MCP specification (version 2024-11-05). Each message is a single JSON line.
// Initialize
→ {"jsonrpc":"2.0","id":1,"method":"initialize","params":{
"protocolVersion":"2024-11-05",
"clientInfo":{"name":"my-client","version":"1.0"}
}}
// Call a tool
→ {"jsonrpc":"2.0","id":2,"method":"tools/call","params":{
"name":"host_list","arguments":{}
}}
// Response
← {"jsonrpc":"2.0","id":2,"result":{
"content":[{"type":"text","text":"[{\"id\":\"...\",\"label\":\"prod-api\",...}]"}]
}}