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": {
      "enabled": true,
      "example_terminal_command": "tmcp call context7__resolve-library-id '<json-string-args>'",
      "description": "Finds the Context7 library ID for a package",
      "parameters": { ... }
    }
  }
}

Step 4: Disable Tools (Optional)

Edit the generated ./terminal-mcp/tools.json file and set enabled: false for any tools you don't want your agent to use.

Step 5: Modify your Agent's Instructions File

For example, OpenAI's Codex Cloud SWE Agent uses AGENTS.md to understand how to work with your codebase. Here's an example prompt you can add:

## Using MCP Tools

You have access to MCP (Model Context Protocol) tools via the `tmcp` CLI. These tools allow you to:

- Search documentation and code repositories
- Access various APIs and services
- Perform specialized tasks

### How to Use MCP Tools

1. **List available tools**: Run `tmcp list` to see all available tools with their descriptions and parameters
2. **Call a tool**: Use `tmcp call <tool-name> '<json-parameters>'`

### Available Tools

<describe the tools here to help your agent understand what they can do and when to use them>

### Example Usage

```bash
# List all available tools
tmcp list

# Search documentation (example with ref tool)
tmcp call ref__search_documentation '{"query": "React useState hook examples"}'

# Resolve a library ID (example with context7 tool)
tmcp call context7__resolve_library_id '{"libraryName": "express"}'
```

### Important Notes

- Tool names use the format `server__tool-name` (double underscore)
- Parameters must be valid JSON strings
- Use single quotes around the JSON parameter string
- Check `tmcp list` output for exact parameter names and types for each tool.

Step 6: Install the agent version of the terminal-mcp CLI

Add this install command to your agent's setup script that will be run before every task:

# Add this line to your setup script (agent-safe version)
curl -fsSL https://raw.githubusercontent.com/zueai/terminal-mcp/main/install-agent.sh | bash

In Codex, you can add this in the Setup Script section when configuring your environment.

---

What's Different in the Agent Binary?

The agent version is a separate, security-focused binary that:

✅ Allows Only Safe Operations:

• tmcp list - View configured and enabled tools
• tmcp call <tool-alias> <params> - Execute specific tools

🚫 Blocks Developer Operations:

• tmcp init - Cannot modify tool configurations
• tmcp direct - Cannot bypass pre-configured servers
• tmcp upgrade - Cannot upgrade itself (security restriction)
• --configpath - Cannot switch to different config files

🔒 Security Benefits:

• Agents can only use tools you've explicitly enabled
• No way to discover or access unauthorized servers
• Cannot modify which tools are available
• Smaller binary footprint with only essential features

This ensures AI agents stay within the boundaries you've set as a developer while still having full access to the tools they need to be productive.

---

Usage

Command Line Options

The CLI supports several options that can be used with any command:

• -h, --help: Show help information and usage examples
• -v, --version: Display version information
• --debug: Enable detailed debug logging
• --configpath <path>: Specify a custom path for the MCP configuration file

Examples:

# Show help
tmcp --help
tmcp -h

# Show version
tmcp --version
tmcp -v

# Use custom config file
tmcp --configpath ./custom/mcp.json init
tmcp --configpath /path/to/config.json list

# Enable debug mode
tmcp --debug call tool-alias '{"param": "value"}'

---

Commands

init - Initialize Configuration

Discovers tools from your configured MCP servers and generates tools.json with all available tools.

# Use configuration from .cursor/mcp.json or mcp.json
tmcp init

# Use custom configuration file
tmcp --configpath /path/to/config.json init

upgrade - Update to Latest Version

Checks for and downloads the latest version of tmcp from GitHub releases.

# Check for updates and upgrade if available
tmcp upgrade

Note: The upgrade command is only available in the full developer version, not in the agent version for security reasons.

list - Show Available Tools

Displays all enabled tools with their schemas and example usage. Disabled tools are automatically filtered out.

# List all enabled tools from configured servers
tmcp list

# List with custom config
tmcp --configpath ./config/mcp.json list

call - Execute Tools

Call tools using their generated aliases (format: server__tool-name). Only enabled tools can be called.

# Call a tool with JSON parameters
tmcp call context7__resolve-library-id '{"libraryName": "react"}'

# Call with debug output
tmcp --debug call ref__search_documentation '{"query": "React hooks"}'

direct - Direct Server Communication

Communicate with MCP servers directly without configuration files.

# List tools from any server
tmcp direct https://mcp.context7.com/mcp list

# Call tools directly using original names
tmcp direct https://mcp.context7.com/mcp call resolve-library-id '{"libraryName": "react"}'

For detailed examples and advanced usage, see: Direct Communication Guide

---

Documentation

• 📖 Development Guide - Setup, development commands, and contributing guidelines
• 🔧 Manual Installation - Detailed installation instructions for all platforms
• 🌐 Direct Communication - Using MCP servers without configuration files

---

License

Apache 2.0