MCP Server

shuck ships with an MCP (Model Context Protocol) server, allowing agents to call shuck_run directly during agent loops. This is the most integrated way for agents to use shuck — instead of generating bash commands, the agent calls shuck as a structured function.

What is MCP?

Model Context Protocol is an open standard for exposing tools to LLMs. Instead of generating bash commands for the agent to run, MCP lets the LLM call your tool as a structured function call.

Tool Schema

shuck exposes a single MCP tool:

{
  "name": "shuck_run",
  "description": "Run an interactive CLI command non-interactively and return clean output. Allocates a PTY so interactive programs behave correctly, strips ANSI sequences, returns clean UTF-8 text.",
  "inputSchema": {
    "type": "object",
    "properties": {
      "command": {
        "type": "string",
        "description": "The CLI command to run (must be in PATH or absolute path)"
      },
      "args": {
        "type": "array",
        "items": {"type": "string"},
        "description": "Arguments to pass to the command",
        "default": []
      },
      "input": {
        "type": "string",
        "description": "Input to feed to the command's stdin"
      },
      "timeout_secs": {
        "type": "integer",
        "description": "Timeout in seconds",
        "default": 30
      },
      "json_output": {
        "type": "boolean",
        "description": "Return structured JSON instead of plain text",
        "default": false
      }
    },
    "required": ["command"]
  }
}

Starting the MCP Server

Stdio Transport (for local use with Claude Desktop)

shuck --mcp-stdio

HTTP/SSE Transport (for remote agents)

shuck --mcp-http --port 3000

Claude Desktop Configuration

Add to ~/Library/Application Support/Claude/claude_desktop_config.json (macOS):

{
  "mcpServers": {
    "shuck": {
      "command": "shuck",
      "args": ["--mcp-stdio"]
    }
  }
}

Now Claude Desktop can call shuck_run directly during conversations.

Example Interaction

With shuck configured as an MCP tool, an agent can call:

{
  "tool": "shuck_run",
  "input": {
    "command": "psql",
    "args": ["-U", "postgres", "mydb"],
    "input": "\\dt"
  }
}

And receive:

{
  "stdout": "        List of relations\n Schema | Name  | Type  | Owner\n...",
  "exit_code": 0,
  "duration_ms": 85,
  "timed_out": false
}

Agent Use Cases via MCP

• Database inspection: Agent calls shuck_run with psql, mysql, or redis-cli to inspect schemas, run queries, check data
• System diagnostics: Agent calls shuck_run with brew doctor, pip check, or npm doctor to diagnose environment issues
• Container debugging: Agent calls shuck_run with docker exec or docker compose to inspect running containers
• Remote commands: Agent calls shuck_run with ssh to execute commands on remote hosts
• Version management: Agent calls shuck_run with nvm ls, pyenv versions, or rustup show to check installed versions

Railway Deployment

Deploy shuck MCP server on Railway for remote agent access:

# railway.toml
[build]
builder = "nixpacks"

[deploy]
startCommand = "shuck --mcp-http --port $PORT"
healthcheckPath = "/health"

# Deploy
railway up
railway domain
# → shuck-mcp.railway.app

Then configure your agent to use the HTTP endpoint:

{
  "mcpServers": {
    "shuck": {
      "url": "https://shuck-mcp.railway.app/sse"
    }
  }
}

Security

The MCP server only exposes the shuck_run tool. It runs with the permissions of the user who started the server. Consider:

• Running with a restricted user if exposing over HTTP
• Using allowlists to restrict which commands can be called
• Setting a global timeout lower than the default 30 seconds

# Example: restricted server
shuck --mcp-http --port 3000 --allow-commands python3,node,psql,mysql,redis-cli