terminal-mcp (tmcp)

A minimal, zero-dependency terminal MCP client built for coding agents.

This project lets coding agents without native MCP support (like OpenAI’s Codex) call MCP tools using simple terminal commands.

Supports both local (via stdio) and remote (via streamable HTTP) MCP servers.

Features

• 🚀 Zero Dependencies: Standalone executable that doesn’t require Node.js, Python, or any other runtime to be installed
• 🌐 Cross-Platform: Works on Linux (x64 & ARM64) and macOS (Intel & Apple Silicon)
• ⚡ Fast Startup: Launches in under 100ms
• 🔧 Supports mcp.json config: Support for common configuration files from popular MCP clients (Cursor, Claude Code, etc.)
• 🔐 Authentication: Support for custom headers and environment variables
• 🎯 Direct Tool Calls: Connect to any MCP server without configuration
• 📦 Agent-Safe Binary: Zero risk of config changes or bypassing security controls because your agent literally gets a different binary that only allows listing and calling pre-configured tools.
• 🛡️ Optimized for Codex: Automatically formats all output to ensure no line exceeds 1550 bytes, preventing crashes in OpenAI Codex Cloud Shell environments that have a 1600 byte line limit. JSON responses are intelligently broken at word boundaries while preserving structure validity.

---

Quick Start for Devs

Step 1: Install the Full Developer Version

Run the auto-install script to install the developer version of tmcp for your OS (Mac/Linux) which gives you full control:

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

Your agent will use a different install script to install the agent-safe binary that only allows safe operations. See Step 6 below.

For detailed manual installation instructions, see: Manual Installation Guide

Step 2: Create MCP Config JSON file (Optional)

If you already have a ./.cursor/mcp.json or ./mcp.json you can skip this step.

Create an MCP configuration file at ./terminal-mcp/servers.json with your MCP servers in the following format:

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

Supported Options

• url or serverUrl: The MCP server endpoint
• headers: Custom HTTP headers to send with requests
• env: Environment variables to set before connecting (OAuth is currently not supported)

Step 3: Initialize and Discover Tools

Run this command to parse your MCP config and discover all tools from every server in your config:

tmcp init

This will create terminal-mcp/tools.json file with the following structure:

{
  "mcpTools": {
    "context7__resolve-library-id": {