Documentation

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:

Binary path by OS
# macOS
/Applications/Shellcat.app/Contents/MacOS/shellcat-mcp

# Windows
C:\Program Files\Shellcat\shellcat-mcp.exe

# Linux
/usr/bin/shellcat-mcp

3. Configure your MCP client

Add the shellcat server to your MCP client config. For Claude Desktop, edit claude_desktop_config.json:

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_execute

Execute a command on a remote server via SSH. Returns stdout, stderr and exit code.

hostrequiredHost ID or label
commandrequiredShell command to execute

SFTP

sftp_list

List files and directories at a path on a remote server.

hostrequiredHost ID or label
pathrequiredRemote path
sftp_readmax 1MB

Read the contents of a text file on a remote server.

hostrequiredHost ID or label
pathrequiredRemote file path
sftp_write

Write content to a file on a remote server.

hostrequiredHost ID or label
pathrequiredRemote file path
contentrequiredFile content to write
sftp_mkdir

Create a directory (and parents) on a remote server.

hostrequiredHost ID or label
pathrequiredRemote directory path
sftp_delete

Delete a file or empty directory on a remote server.

hostrequiredHost ID or label
pathrequiredRemote path

Hosts

host_list

List all saved SSH hosts with connection details.

host_create

Add a new SSH host to the saved hosts list.

labelrequiredDisplay name
hostnamerequiredServer hostname or IP
usernamerequiredSSH username
portSSH port (default: 22)
auth_methodpassword or key
groupHost group name
host_delete

Delete a saved SSH host.

hostrequiredHost ID or label

Snippets

snippet_list

List all saved command snippets.

snippet_create

Create a new command snippet.

labelrequiredDisplay name
commandrequiredShell command to execute
descriptionDescription (optional)
snippet_delete

Delete a saved snippet.

snippetrequiredSnippet ID or label
snippet_execute

Execute a saved snippet on a remote host via SSH.

snippetrequiredSnippet ID or label
hostrequiredHost ID or label

Password Vault

vault_status

Check if the vault is unlocked and if a master password has been set up.

vault_unlock

Unlock the vault with the master password.

master_passwordrequiredMaster password
vault_list

List vault entries (titles, usernames, URLs). Passwords are not returned.

categoryFilter by category
vault_get

Get a vault entry with decrypted password (requires unlock).

entryrequiredEntry ID or title
vault_create

Create a new vault entry. Password and notes are encrypted.

titlerequiredEntry title
usernamerequiredSSH username
passwordrequiredPassword to store
urlWebsite URL
categoryFilter by category
vault_delete

Delete a vault entry.

entryrequiredEntry ID or title

Authentication

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.

Unlock flow
// 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:

Claude Desktop
stdio
Claude Code
stdio
Cursor
stdio
Windsurf
stdio

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.

JSON-RPC example
// 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\",...}]"}]
  }}

Ready to connect AI to your servers?

Download Shellcat, build the MCP binary, and start automating.

Download Free