{"id":29269676,"url":"https://github.com/zueai/terminal-mcp","last_synced_at":"2025-10-18T10:23:50.770Z","repository":{"id":301250929,"uuid":"1008080743","full_name":"zueai/terminal-mcp","owner":"zueai","description":"A minimal, zero-dependency terminal MCP (Model Context Protocol) client built for coding agents like OpenAI Codex.","archived":false,"fork":false,"pushed_at":"2025-06-25T23:14:28.000Z","size":136,"stargazers_count":1,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2025-06-25T23:25:23.212Z","etag":null,"topics":["cli","mcp","model-context-protocol","terminal"],"latest_commit_sha":null,"homepage":"","language":"Shell","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/zueai.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2025-06-25T02:08:42.000Z","updated_at":"2025-06-25T23:14:30.000Z","dependencies_parsed_at":"2025-06-25T23:25:29.142Z","dependency_job_id":"99d8096e-62b6-494e-af10-5b12144872ab","html_url":"https://github.com/zueai/terminal-mcp","commit_stats":null,"previous_names":["zueai/terminal-mcp"],"tags_count":13,"template":false,"template_full_name":null,"purl":"pkg:github/zueai/terminal-mcp","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/zueai%2Fterminal-mcp","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/zueai%2Fterminal-mcp/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/zueai%2Fterminal-mcp/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/zueai%2Fterminal-mcp/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/zueai","download_url":"https://codeload.github.com/zueai/terminal-mcp/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/zueai%2Fterminal-mcp/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":263619808,"owners_count":23489563,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["cli","mcp","model-context-protocol","terminal"],"created_at":"2025-07-04T21:07:59.996Z","updated_at":"2025-09-23T20:52:01.950Z","avatar_url":"https://github.com/zueai.png","language":"Shell","funding_links":[],"categories":[],"sub_categories":[],"readme":"# terminal-mcp (tmcp)\n\n## A minimal, zero-dependency terminal MCP client built for coding agents.\n\nThis project lets coding agents without native MCP support (like OpenAI's Codex) call MCP tools using simple terminal commands.\n\nSupports both local (via stdio) and remote (via streamable HTTP) MCP servers.\n\n## Features\n\n- 🚀 **Zero Dependencies**: Standalone executable that doesn't require Node.js, Python, or any other runtime to be installed\n- 🌐 **Cross-Platform**: Works on Linux (x64 \u0026 ARM64) and macOS (Intel \u0026 Apple Silicon)\n- ⚡ **Fast Startup**: Launches in under 100ms\n- 🔧 **Supports mcp.json config**: Support for common configuration files from popular MCP clients (Cursor, Claude Code, etc.)\n- 🔐 **Authentication**: Support for custom headers and environment variables\n- 🎯 **Direct Tool Calls**: Connect to any MCP server without configuration\n- 📦 **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.\n- 🛡️ **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.\n\n---\n\n## Quick Start for Devs\n\n### Step 1: Install the Full Developer Version\n\nRun the auto-install script to install the developer version of `tmcp` for your OS (Mac/Linux) which gives you full control:\n\n```bash\ncurl -fsSL https://raw.githubusercontent.com/zueai/terminal-mcp/main/install.sh | bash\n```\n\nYour agent will use a different install script to install the agent-safe binary that only allows safe operations. See [Step 6](#step-6-install-the-agent-version-of-the-terminal-mcp-cli) below.\n\nFor detailed manual installation instructions, see: [Manual Installation Guide](docs/MANUAL_INSTALLATION.md)\n\n### Step 2: Create MCP Config JSON file (Optional)\n\nIf you already have a `./.cursor/mcp.json` or `./mcp.json` you can skip this step.\n\nCreate an MCP configuration file at `./terminal-mcp/servers.json` with your MCP servers in the following format:\n```json\n{\n  \"mcpServers\": {\n    \"context7\": {\n      \"url\": \"https://mcp.context7.com/mcp\"\n    },\n    \"ref\": {\n      \"url\": \"http://api.ref.tools/mcp\",\n      \"headers\": {\n        \"x-ref-api-key\": \"your-api-key\"\n      }\n    }\n  }\n}\n```\n\n**Supported Options**\n\n- **`url` or `serverUrl`**: The MCP server endpoint\n- **`headers`**: Custom HTTP headers to send with requests\n- **`env`**: Environment variables to set before connecting (OAuth is currently not supported)\n\n### Step 3: Initialize and Discover Tools\n\nRun this command to parse your MCP config and discover all tools from every server in your config:\n```bash\ntmcp init\n```\n\nThis will create `terminal-mcp/tools.json` file with the following structure:\n```json\n{\n  \"mcpTools\": {\n    \"context7__resolve-library-id\": {\n      \"enabled\": true,\n      \"example_terminal_command\": \"tmcp call context7__resolve-library-id '\u003cjson-string-args\u003e'\",\n      \"description\": \"Finds the Context7 library ID for a package\",\n      \"parameters\": { ... }\n    }\n  }\n}\n```\n\n### Step 4: Disable Tools (Optional)\n\nEdit the generated `./terminal-mcp/tools.json` file and set `enabled: false` for any tools you don't want your agent to use.\n\n### Step 5: Modify your Agent's Instructions File\n\nFor 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:\n\n````markdown\n## Using MCP Tools\n\nYou have access to MCP (Model Context Protocol) tools via the `tmcp` CLI. These tools allow you to:\n\n- Search documentation and code repositories\n- Access various APIs and services\n- Perform specialized tasks\n\n### How to Use MCP Tools\n\n1. **List available tools**: Run `tmcp list` to see all available tools with their descriptions and parameters\n2. **Call a tool**: Use `tmcp call \u003ctool-name\u003e '\u003cjson-parameters\u003e'`\n\n### Available Tools\n\n\u003cdescribe the tools here to help your agent understand what they can do and when to use them\u003e\n\n### Example Usage\n\n```bash\n# List all available tools\ntmcp list\n\n# Search documentation (example with ref tool)\ntmcp call ref__search_documentation '{\"query\": \"React useState hook examples\"}'\n\n# Resolve a library ID (example with context7 tool)\ntmcp call context7__resolve_library_id '{\"libraryName\": \"express\"}'\n```\n\n### Important Notes\n\n- Tool names use the format `server__tool-name` (double underscore)\n- Parameters must be valid JSON strings\n- Use single quotes around the JSON parameter string\n- Check `tmcp list` output for exact parameter names and types for each tool.\n````\n\n### Step 6: Install the agent version of the terminal-mcp CLI\n\nAdd this install command to your agent's setup script that will be run before every task:\n\n```bash\n# Add this line to your setup script (agent-safe version)\ncurl -fsSL https://raw.githubusercontent.com/zueai/terminal-mcp/main/install-agent.sh | bash\n```\n\nIn Codex, you can add this in the `Setup Script` section when configuring your environment.\n\n---\n\n### What's Different in the Agent Binary?\n\nThe agent version is a separate, security-focused binary that:\n\n**✅ Allows Only Safe Operations:**\n- `tmcp list` - View configured and enabled tools\n- `tmcp call \u003ctool-alias\u003e \u003cparams\u003e` - Execute specific tools\n\n**🚫 Blocks Developer Operations:**\n- `tmcp init` - Cannot modify tool configurations\n- `tmcp direct` - Cannot bypass pre-configured servers\n- `tmcp upgrade` - Cannot upgrade itself (security restriction)\n- `--configpath` - Cannot switch to different config files\n\n**🔒 Security Benefits:**\n- Agents can only use tools you've explicitly enabled\n- No way to discover or access unauthorized servers\n- Cannot modify which tools are available\n- Smaller binary footprint with only essential features\n\nThis 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.\n\n---\n\n## Usage\n\n### Command Line Options\n\nThe CLI supports several options that can be used with any command:\n\n- **`-h, --help`**: Show help information and usage examples\n- **`-v, --version`**: Display version information\n- **`--debug`**: Enable detailed debug logging\n- **`--configpath \u003cpath\u003e`**: Specify a custom path for the MCP configuration file\n\nExamples:\n```bash\n# Show help\ntmcp --help\ntmcp -h\n\n# Show version\ntmcp --version\ntmcp -v\n\n# Use custom config file\ntmcp --configpath ./custom/mcp.json init\ntmcp --configpath /path/to/config.json list\n\n# Enable debug mode\ntmcp --debug call tool-alias '{\"param\": \"value\"}'\n```\n\n---\n\n## Commands\n\n### `init` - Initialize Configuration\n\nDiscovers tools from your configured MCP servers and generates tools.json with all available tools.\n\n```bash\n# Use configuration from .cursor/mcp.json or mcp.json\ntmcp init\n\n# Use custom configuration file\ntmcp --configpath /path/to/config.json init\n```\n\n### `upgrade` - Update to Latest Version\n\nChecks for and downloads the latest version of tmcp from GitHub releases.\n\n```bash\n# Check for updates and upgrade if available\ntmcp upgrade\n\n\n```\n\n**Note:** The upgrade command is only available in the full developer version, not in the agent version for security reasons.\n\n### `list` - Show Available Tools\n\nDisplays all enabled tools with their schemas and example usage. Disabled tools are automatically filtered out.\n\n```bash\n# List all enabled tools from configured servers\ntmcp list\n\n# List with custom config\ntmcp --configpath ./config/mcp.json list\n```\n\n### `call` - Execute Tools\n\nCall tools using their generated aliases (format: `server__tool-name`). Only enabled tools can be called.\n\n```bash\n# Call a tool with JSON parameters\ntmcp call context7__resolve-library-id '{\"libraryName\": \"react\"}'\n\n# Call with debug output\ntmcp --debug call ref__search_documentation '{\"query\": \"React hooks\"}'\n```\n\n### `direct` - Direct Server Communication\n\nCommunicate with MCP servers directly without configuration files.\n\n```bash\n# List tools from any server\ntmcp direct https://mcp.context7.com/mcp list\n\n# Call tools directly using original names\ntmcp direct https://mcp.context7.com/mcp call resolve-library-id '{\"libraryName\": \"react\"}'\n```\n\nFor detailed examples and advanced usage, see: [Direct Communication Guide](docs/DIRECT_COMMUNICATION.md)\n\n---\n\n## Documentation\n\n- 📖 [Development Guide](docs/DEVELOPMENT.md) - Setup, development commands, and contributing guidelines\n- 🔧 [Manual Installation](docs/MANUAL_INSTALLATION.md) - Detailed installation instructions for all platforms\n- 🌐 [Direct Communication](docs/DIRECT_COMMUNICATION.md) - Using MCP servers without configuration files\n\n---\n\n## License\n\nMIT\n\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fzueai%2Fterminal-mcp","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fzueai%2Fterminal-mcp","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fzueai%2Fterminal-mcp/lists"}