Read

Tool Name: files/read

Reads a text file and returns its contents as raw text (no line numbers or metadata). Read-only; path must be absolute. To find a file use files/find, for size or mode files/list, to check whether it is binary files/filetype (binary files are refused with cannot read binary file). Selection: start_line/end_line (1-indexed, inclusive; start_line alone reads to the end, end_line alone starts at line 1) take precedence over the byte range offset/limit. With no selection, or offset without limit, at most 10240 bytes come back followed by a [WARNING: File truncated ...] line, so page large files with start_line/end_line or pass limit. There is no streaming: one call reads into memory, and a line over 64 KiB fails line mode. A start_line past the end is an error; an empty file returns an empty string. privileged: true (needs a grant, and a paths: entry for root) reads files your account cannot.

Arguments

Argument	Type	Required	Description
path	string	yes	Absolute path of the file to read
end_line	integer	no	Last line to return (inclusive); alone it starts at line 1. Ignored if below start_line
limit	integer	no	Number of bytes to return (no upper cap). With no selection at all, the first 10240 bytes are returned
offset	integer	no	Byte offset to start at; ignored when start_line/end_line is given. Without limit at most 10240 bytes are returned
privileged	boolean	no	Run as root. Needs a grant for this tool in mcp-sudo.yaml and a paths: entry covering the path, otherwise refused
start_line	integer	no	First line to return (1-indexed). With or without end_line it takes precedence over offset/limit; alone it reads to the end of the file

Example

Every example below shows the equivalent linuxctl command and the raw MCP JSON-RPC call it resolves to. The raw call always follows the same two-step pattern (see MCP API overview for the full explanation): open an SSE stream to get a one-time POST endpoint, then POST the JSON-RPC request there - the result streams back on the SSE connection.

linuxctl

linuxctl get files /etc/hosts

Output (Ubuntu 24.04 VPS):

# Generated by SolusVM
127.0.0.1	localhost localhost.localdomain
::1	localhost localhost.localdomain
203.0.113.117	vps.example.com

curl (raw MCP JSON-RPC)

# 1. Open the SSE stream (in the background) and capture the one-time POST endpoint
curl -N -s --cacert mcpd.crt -H "Authorization: Bearer $MCP_TOKEN" https://localhost:9091/sse &
# server sends: event: endpoint / data: /message?session_id=...

# 2. POST the tools/call request to that endpoint
curl -s --cacert mcpd.crt -X POST "https://localhost:9091/message?session_id=<from step 1>" \
  -H "Authorization: Bearer $MCP_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc": "2.0", "id": "1", "method": "tools/call", "params": {"name": "files/read", "arguments": {"path": "/etc/hosts"}}}'

# 3. The result arrives on the SSE stream opened in step 1

Response:

{
  "jsonrpc": "2.0",
  "id": "1",
  "result": {
    "content": [
      {
        "type": "text",
        "text": "# Generated by SolusVM\n127.0.0.1\tlocalhost localhost.localdomain\n::1\tlocalhost localhost.localdomain\n203.0.113.117\tvps.example.com"
      }
    ]
  }
}