terminal

terminal-mcp (tmcp) is a zero-dependency, agent-safe MCP client that runs as a standalone binary. It lets coding agents interact with MCP servers by discovering available tools from configured MCP endpoints and then calling those tools via the tmcp CLI. You first initialize your configuration to discover tools from one or more MCP servers, then list the available tools and call them using tool aliases in the format server__tool-name. The client focuses on safety: the agent-specific binary restricts certain commands to prevent config tampering, while still giving you access to a pre-configured set of tools. If you already have a mcp.json or cursor-style config, tmcp can read from it to populate its tool set; otherwise you can use a generated servers.json to point at MCP endpoints and headers. Typical workflow: install tmcp, create or point to a servers.json describing your MCP servers, run tmcp init to discover tools, then tmcp list to view enabled tools and tmcp call <server>__<tool> '<params>' to execute a tool.

Prerequisites:

• A Unix-like OS (Linux or macOS) with curl and bash available
• Internet access to fetch scripts

Step 1 – Install the full developer version (optional for testing and full control):

curl -fsSL https://raw.githubusercontent.com/zueai/terminal-mcp/main/install.sh | bash

This installs the developer version of the terminal-mcp CLI. The agent-safe binary is installed separately as described in Step 6.

Step 2 – Create MCP config (servers.json) if you don’t have one:

• Place your MCP server definitions in a file such as ./terminal-mcp/servers.json with structure like:

{
  "mcpServers": {
    "context7": {
      "url": "https://mcp.context7.com/mcp"
    },
    "ref": {
      "url": "http://api.ref.tools/mcp",
      "headers": {
        "x-ref-api-key": "your-api-key"
      }
    }
  }
}

Step 3 – Initialize and discover tools:

tmcp init

This reads your servers.json and writes a terminal-mcp/tools.json file with available tools.

Step 4 – (Optional) Use the agent-safe binary for restricted environments:

curl -fsSL https://raw.githubusercontent.com/zueai/terminal-mcp/main/install-agent.sh | bash

This installs the agent-restricted binary that only allows listing and calling pre-configured tools. If using the agent version, ensure you use tmcp list and tmcp call as described in Step 5.

Step 5 – Basic usage:

# List available tools
tmcp list

# Call a tool (example alias):
tmcp call context7__resolve-library-id '{"libraryName": "react"}'

Step 6 – Manual installation guide (advanced):

• Download the binary for your OS from the repository releases page.
• Make it executable: chmod +x tmcp
• Move it to a directory in your PATH, e.g. sudo mv tmcp /usr/local/bin/
• Ensure your servers.json (or mcp.json) is accessible and formatted correctly.

Notes:

• If you already have a ./cursor/mcp.json or ./mcp.json, tmcp can reuse it during init.
• You can customize the config path via --configpath when invoking tmcp.

Tips and caveats:

• Tools are exposed as aliases in the format server__tool-name; use tmcp list to view exact aliases and their parameters.
• To restrict tools for an agent, edit the generated terminal-mcp/tools.json and disable unwanted tools by setting enabled to false.
• If your MCP server requires custom HTTP headers, add them under headers in servers.json. You can also specify environment variables under env if the server supports them.
• The agent version blocks commands that would modify tool configurations or switch configs to maintain security boundaries.
• For large JSON parameters, ensure your strings are valid JSON and wrap them in single quotes when used in the shell to avoid shell escaping issues.