Skip to content
Back to search

mcp-cli

SkillWorks with Claude CodeGitHub

Interface for MCP (Model Context Protocol) servers via CLI. Use when you need to interact with external tools, APIs, or data sources through MCP servers.

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today
Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/philschmid--mcp-cli/badge.svg)](/listings/philschmid--mcp-cli)

HTML

<a href="/listings/philschmid--mcp-cli"><img src="/api/listings/philschmid--mcp-cli/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

These steps run a script from the network that findsafeskills does not scan.

1. Installation

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

or

# requires bun install
bun install -g https://github.com/philschmid/mcp-cli

2. Create a config file

Create `mcp_servers.json` in your current directory or `~/.config/mcp/`:

{
  "mcpServers": {
    "filesystem": {
      "command": "npx",
      "args": [
        "-y",
        "@modelcontextprotocol/server-filesystem",
        "."
      ]
    },
    "deepwiki": {
      "url": "https://mcp.deepwiki.com/mcp"
    }
  }
}

3. Discover available tools

# List all servers and tools
mcp-cli

# With descriptions
mcp-cli -d

4. Call a tool

# View tool schema first
mcp-cli info filesystem read_file

# Call the tool
mcp-cli call filesystem read_file '{"path": "./README.md"}'

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

SKILL.md · Manifest · 110 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

  1. ---
  2. name: mcp-cli
  3. description: Interface for MCP (Model Context Protocol) servers via CLI. Use when you need to interact with external tools, APIs, or data sources through MCP servers.
  4. ---
  5. # MCP-CLI
  6. Access MCP servers through the command line. MCP enables interaction with external systems like GitHub, filesystems, databases, and APIs.
  7. ## Commands
  8. | Command | Output |
  9. |---------|--------|
  10. | `mcp-cli` | List all servers and tools |
  11. | `mcp-cli info <server>` | Show server tools and parameters |
  12. | `mcp-cli info <server> <tool>` | Get tool JSON schema |
  13. | `mcp-cli grep "<pattern>"` | Search tools by name |
  14. | `mcp-cli call <server> <tool>` | Call tool (reads JSON from stdin if no args) |
  15. | `mcp-cli call <server> <tool> '<json>'` | Call tool with arguments |
  16. **Both formats work:** `<server> <tool>` or `<server>/<tool>`
  17. ## Workflow
  18. 1. **Discover**: `mcp-cli` → see available servers
  19. 2. **Explore**: `mcp-cli info <server>` → see tools with parameters
  20. 3. **Inspect**: `mcp-cli info <server> <tool>` → get full JSON schema
  21. 4. **Execute**: `mcp-cli call <server> <tool> '<json>'` → run with arguments
  22. ## Examples
  23. ```bash
  24. # List all servers
  25. mcp-cli
  26. # With descriptions
  27. mcp-cli -d
  28. # See server tools
  29. mcp-cli info filesystem
  30. # Get tool schema (both formats work)
  31. mcp-cli info filesystem read_file
  32. mcp-cli info filesystem/read_file
  33. # Call tool
  34. mcp-cli call filesystem read_file '{"path": "./README.md"}'
  35. # Pipe from stdin (no '-' needed!)
  36. cat args.json | mcp-cli call filesystem read_file
  37. # Search for tools
  38. mcp-cli grep "*file*"
  39. # Output is raw text (pipe-friendly)
  40. mcp-cli call filesystem read_file '{"path": "./file"}' | head -10
  41. ```
  42. ## Advanced Chaining
  43. ```bash
  44. # Chain: search files → read first match
  45. mcp-cli call filesystem search_files '{"path": ".", "pattern": "*.md"}' \
  46. | head -1 \
  47. | xargs -I {} mcp-cli call filesystem read_file '{"path": "{}"}'
  48. # Loop: process multiple files
  49. mcp-cli call filesystem list_directory '{"path": "./src"}' \
  50. | while read f; do mcp-cli call filesystem read_file "{\"path\": \"$f\"}"; done
  51. # Conditional: check before reading
  52. mcp-cli call filesystem list_directory '{"path": "."}' \
  53. | grep -q "README" \
  54. && mcp-cli call filesystem read_file '{"path": "./README.md"}'
  55. # Multi-server aggregation
  56. {
  57. mcp-cli call github search_repositories '{"query": "mcp", "per_page": 3}'
  58. mcp-cli call filesystem list_directory '{"path": "."}'
  59. }
  60. # Save to file
  61. mcp-cli call github get_file_contents '{"owner": "x", "repo": "y", "path": "z"}' > output.txt
  62. ```
  63. **Note:** `call` outputs raw text content directly (no jq needed for text extraction)
  64. ## Options
  65. | Flag | Purpose |
  66. |------|---------|
  67. | `-d` | Include descriptions |
  68. | `-c <path>` | Specify config file |
  69. ## Common Errors
  70. | Wrong Command | Error | Fix |
  71. |---------------|-------|-----|
  72. | `mcp-cli server tool` | AMBIGUOUS_COMMAND | Use `call server tool` or `info server tool` |
  73. | `mcp-cli run server tool` | UNKNOWN_SUBCOMMAND | Use `call` instead of `run` |
  74. | `mcp-cli list` | UNKNOWN_SUBCOMMAND | Use `info` instead of `list` |
  75. | `mcp-cli call server` | MISSING_ARGUMENT | Add tool name |
  76. | `mcp-cli call server tool {bad}` | INVALID_JSON | Use valid JSON with quotes |
  77. ## Exit Codes
  78. - `0`: Success
  79. - `1`: Client error (bad args, missing config)
  80. - `2`: Server error (tool failed)
  81. - `3`: Network error
README.md · README · 642 lines · 1 finding marked

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

  1. # mcp-cli
  2. A lightweight, Bun-based CLI for interacting with [MCP (Model Context Protocol)](https://modelcontextprotocol.io/) servers.
  3. ## Features
  4. - 🪶 **Lightweight** - Minimal dependencies, fast startup
  5. - 📦 **Single Binary** - Compile to standalone executable via `bun build --compile`
  6. - 🔧 **Shell-Friendly** - JSON output for call, pipes with `jq`, chaining support
  7. - 🤖 **Agent-Optimized** - Designed for AI coding agents (Gemini CLI, Claude Code, etc.)
  8. - 🔌 **Universal** - Supports both stdio and HTTP MCP servers
  9. - ⚡ **Connection Pooling** - Lazy-spawn daemon keeps connections warm (60s idle timeout)
  10. - � **Tool Filtering** - Allow/disable specific tools per server via config
  11. - 📋 **Server Instructions** - Display MCP server instructions in output
  12. - �💡 **Actionable Errors** - Structured error messages with available servers and recovery suggestions
  13. ![mcp-cli](./comparison.jpeg)
  14. ## Quick Start
  15. ### 1. Installation
  16. ```bash
  17. curl -fsSL https://raw.githubusercontent.com/philschmid/mcp-cli/main/install.sh | bash
    • Note: Pipes a downloaded script directly into a shell (curl | sh / wget | bash)
    • Line 24 on GitHub
  18. ```
  19. or
  20. ```bash
  21. # requires bun install
  22. bun install -g https://github.com/philschmid/mcp-cli
  23. ```
  24. ### 2. Create a config file
  25. Create `mcp_servers.json` in your current directory or `~/.config/mcp/`:
  26. ```json
  27. {
  28. "mcpServers": {
  29. "filesystem": {
  30. "command": "npx",
  31. "args": [
  32. "-y",
  33. "@modelcontextprotocol/server-filesystem",
  34. "."
  35. ]
  36. },
  37. "deepwiki": {
  38. "url": "https://mcp.deepwiki.com/mcp"
  39. }
  40. }
  41. }
  42. ```
  43. ### 3. Discover available tools
  44. ```bash
  45. # List all servers and tools
  46. mcp-cli
  47. # With descriptions
  48. mcp-cli -d
  49. ```
  50. ### 4. Call a tool
  51. ```bash
  52. # View tool schema first
  53. mcp-cli info filesystem read_file
  54. # Call the tool
  55. mcp-cli call filesystem read_file '{"path": "./README.md"}'
  56. ```
  57. ## Usage
  58. ```
  59. mcp-cli [options] List all servers and tools
  60. mcp-cli [options] info <server> Show server tools and parameters
  61. mcp-cli [options] info <server> <tool> Show tool schema
  62. mcp-cli [options] grep <pattern> Search tools by glob pattern
  63. mcp-cli [options] call <server> <tool> Call tool (reads JSON from stdin if no args)
  64. mcp-cli [options] call <server> <tool> <json> Call tool with JSON arguments
  65. ```
  66. **Both formats work:** `info <server> <tool>` or `info <server>/<tool>`
  67. > [!TIP]
  68. > Add `-d` to any command to include descriptions.
  69. ### Options
  70. | Option | Description |
  71. |--------|-------------|
  72. | `-h, --help` | Show help message |
  73. | `-v, --version` | Show version number |
  74. | `-d, --with-descriptions` | Include tool descriptions |
  75. | `-c, --config <path>` | Path to config file |
  76. ### Output
  77. | Stream | Content |
  78. |--------|---------|
  79. | **stdout** | Tool results and human-readable info |
  80. | **stderr** | Errors and diagnostics |
  81. ### Commands
  82. #### List Servers
  83. ```bash
  84. # Basic listing
  85. $ mcp-cli
  86. github
  87. • search_repositories
  88. • get_file_contents
  89. • create_or_update_file
  90. filesystem
  91. • read_file
  92. • write_file
  93. • list_directory
  94. # With descriptions
  95. $ mcp-cli --with-descriptions
  96. github
  97. • search_repositories - Search for GitHub repositories
  98. • get_file_contents - Get contents of a file or directory
  99. filesystem
  100. • read_file - Read the contents of a file
  101. • write_file - Write content to a file
  102. ```
  103. #### Search Tools
  104. ```bash
  105. # Find file-related tools across all servers
  106. $ mcp-cli grep "*file*"
  107. github/get_file_contents
  108. github/create_or_update_file
  109. filesystem/read_file
  110. filesystem/write_file
  111. # Search with descriptions
  112. $ mcp-cli grep "*search*" -d
  113. github/search_repositories - Search for GitHub repositories
  114. ```
  115. #### View Server Details
  116. ```bash
  117. $ mcp-cli info github
  118. Server: github
  119. Transport: stdio
  120. Command: npx -y @modelcontextprotocol/server-github
  121. Tools (12):
  122. search_repositories
  123. Search for GitHub repositories
  124. Parameters:
  125. • query (string, required) - Search query
  126. • page (number, optional) - Page number
  127. ...
  128. ```
  129. #### View Tool Schema
  130. ```bash
  131. # Both formats work:
  132. $ mcp-cli info github search_repositories
  133. $ mcp-cli info github/search_repositories
  134. Tool: search_repositories
  135. Server: github
  136. Description:
  137. Search for GitHub repositories
  138. Input Schema:
  139. {
  140. "type": "object",
  141. "properties": {
  142. "query": { "type": "string", "description": "Search query" },
  143. "page": { "type": "number" }
  144. },
  145. "required": ["query"]
  146. }
  147. ```
  148. #### Call a Tool
  149. ```bash
  150. # With inline JSON
  151. $ mcp-cli call github search_repositories '{"query": "mcp server", "per_page": 5}'
  152. # JSON output is default for call command
  153. $ mcp-cli call github search_repositories '{"query": "mcp"}' | jq '.content[0].text'
  154. # Read JSON from stdin (no '-' needed!)
  155. $ echo '{"path": "./README.md"}' | mcp-cli call filesystem read_file
  156. ```
  157. #### Complex Commands
  158. For JSON arguments containing single quotes, special characters, or long text, use **stdin** to avoid shell escaping issues:
  159. ```bash
  160. # Using a heredoc (no '-' needed with call subcommand)
  161. mcp-cli call server tool <<EOF
  162. {"content": "Text with 'single quotes' and \"double quotes\""}
  163. EOF
  164. # From a file
  165. cat args.json | mcp-cli call server tool
  166. # Using jq to build complex JSON
  167. jq -n '{query: "mcp", filters: ["active", "starred"]}' | mcp-cli call github search
  168. ```
  169. **Why stdin?** Shell interpretation of `{}`, quotes, and special characters requires careful escaping. Stdin bypasses shell parsing entirely.
  170. #### Advanced Chaining Examples
  171. Chain multiple MCP calls together using pipes and shell tools:
  172. ```bash
  173. # 1. Search and read: Find files matching pattern, then read the first one
  174. mcp-cli call filesystem search_files '{"path": "src/", "pattern": "*.ts"}' \
  175. | jq -r '.content[0].text | split("\n")[0]' \
  176. | xargs -I {} mcp-cli call filesystem read_file '{"path": "{}"}'
  177. # 2. Process multiple results: Read all matching files
  178. mcp-cli call filesystem search_files '{"path": ".", "pattern": "*.md"}' \
  179. | jq -r '.content[0].text | split("\n")[]' \
  180. | while read file; do
  181. echo "=== $file ==="
  182. mcp-cli call filesystem read_file "{\"path\": \"$file\"}" | jq -r '.content[0].text'
  183. done
  184. # 3. Extract and transform: Get repo info, extract URLs
  185. mcp-cli call github search_repositories '{"query": "mcp server", "per_page": 5}' \
  186. | jq -r '.content[0].text | fromjson | .items[].html_url'
  187. # 4. Conditional execution: Check file exists before reading
  188. mcp-cli call filesystem list_directory '{"path": "."}' \
  189. | jq -e '.content[0].text | contains("README.md")' \
  190. && mcp-cli call filesystem read_file '{"path": "./README.md"}'
  191. # 5. Save output to file
  192. mcp-cli call github get_file_contents '{"owner": "user", "repo": "project", "path": "src/main.ts"}' \
  193. | jq -r '.content[0].text' > main.ts
  194. # 6. Error handling in scripts
  195. if result=$(mcp-cli call filesystem read_file '{"path": "./config.json"}' 2>/dev/null); then
  196. echo "$result" | jq '.content[0].text | fromjson'
  197. else
  198. echo "File not found, using defaults"
  199. fi
  200. # 7. Aggregate results from multiple servers
  201. {
  202. mcp-cli call github search_repositories '{"query": "mcp", "per_page": 3}'
  203. mcp-cli call filesystem list_directory '{"path": "./src"}'
  204. } | jq -s '.'
  205. ```
  206. **Tips for chaining:**
  207. - Use `jq -r` for raw output (no quotes)
  208. - Use `jq -e` for conditional checks (exit code 1 if false)
  209. - Use `2>/dev/null` to suppress errors when testing
  210. - Use `| jq -s '.'` to combine multiple JSON outputs
  211. ## Configuration
  212. ### Config File Format
  213. The CLI uses `mcp_servers.json`, compatible with Claude Desktop, Gemini or VS Code:
  214. ```json
  215. {
  216. "mcpServers": {
  217. "local-server": {
  218. "command": "node",
  219. "args": ["./server.js"],
  220. "env": {
  221. "API_KEY": "${API_KEY}"
  222. },
  223. "cwd": "/path/to/directory"
  224. },
  225. "remote-server": {
  226. "url": "https://mcp.example.com",
  227. "headers": {
  228. "Authorization": "Bearer ${TOKEN}"
  229. }
  230. }
  231. }
  232. }
  233. ```
  234. **Environment Variable Substitution:** Use `${VAR_NAME}` syntax anywhere in the config. Values are substituted at load time. By default, missing environment variables cause an error with a clear message. Set `MCP_STRICT_ENV=false` to use empty values instead (with a warning).
  235. ### Tool Filtering
  236. Restrict which tools are available from a server using `allowedTools` and `disabledTools`:
  237. ```json
  238. {
  239. "mcpServers": {
  240. "filesystem": {
  241. "command": "npx",
  242. "args": ["-y", "@modelcontextprotocol/server-filesystem", "."],
  243. "allowedTools": ["read_file", "list_directory"],
  244. "disabledTools": ["delete_file"]
  245. }
  246. }
  247. }
  248. ```
  249. **Rules:**
  250. - `allowedTools`: Only tools matching these patterns are available (supports glob: `*`, `?`)
  251. - `disabledTools`: Tools matching these patterns are excluded
  252. - **`disabledTools` takes precedence** over `allowedTools`
  253. - Filtering applies globally to all CLI operations (info, grep, call)
  254. **Examples:**
  255. ```json
  256. // Only allow read operations
  257. "allowedTools": ["read_*", "list_*", "search_*"]
  258. // Allow all except destructive operations
  259. "disabledTools": ["delete_*", "write_*", "create_*"]
  260. // Combine: allow file operations but disable delete
  261. "allowedTools": ["*file*"],
  262. "disabledTools": ["delete_file"]
  263. ```
  264. ### Config Resolution
  265. The CLI searches for configuration in this order:
  266. 1. `MCP_CONFIG_PATH` environment variable
  267. 2. `-c/--config` command line argument
  268. 3. `./mcp_servers.json` (current directory)
  269. 4. `~/.mcp_servers.json`
  270. 5. `~/.config/mcp/mcp_servers.json`
  271. ### Environment Variables
  272. | Variable | Description | Default |
  273. |----------|-------------|---------|
  274. | `MCP_CONFIG_PATH` | Path to config file | (none) |
  275. | `MCP_DEBUG` | Enable debug output | `false` |
  276. | `MCP_TIMEOUT` | Request timeout (seconds) | `1800` (30 min) |
  277. | `MCP_CONCURRENCY` | Servers processed in parallel (not a limit on total) | `5` |
  278. | `MCP_MAX_RETRIES` | Retry attempts for transient errors (0 = disable) | `3` |
  279. | `MCP_RETRY_DELAY` | Base retry delay (milliseconds) | `1000` |
  280. | `MCP_STRICT_ENV` | Error on missing `${VAR}` in config | `true` |
  281. | `MCP_NO_DAEMON` | Disable connection caching (force fresh connections) | `false` |
  282. | `MCP_DAEMON_TIMEOUT` | Idle timeout for cached connections (seconds) | `60` |
  283. ## Using with AI Agents
  284. `mcp-cli` is designed to give AI coding agents access to MCP (Model Context Protocol) servers. MCP enables AI models to interact with external tools, APIs, and data sources through a standardized protocol.
  285. ### Why MCP + CLI?
  286. Traditional MCP integration loads full tool schemas into the AI's context window, consuming thousands of tokens. The CLI approach:
  287. - **On-demand loading**: Only fetch schemas when needed
  288. - **Token efficient**: Minimal context overhead
  289. - **Shell composable**: Chain with `jq`, pipes, and scripts
  290. - **Scriptable**: AI can write shell scripts for complex workflows
  291. ### Option 1: System Prompt Integration
  292. Add this to your AI agent's system prompt for direct CLI access:
  293. ````xml
  294. ## MCP Servers
  295. You have access to MCP servers via the `mcp-cli` CLI.
  296. Commands:
  297. ```bash
  298. mcp-cli info # List all servers
  299. mcp-cli info <server> # Show server tools
  300. mcp-cli info <server> <tool> # Get tool schema
  301. mcp-cli grep "<pattern>" # Search tools
  302. mcp-cli call <server> <tool> # Call tool (stdin auto-detected)
  303. mcp-cli call <server> <tool> '{}' # Call with JSON args
  304. ```
  305. **Both formats work:** `info <server> <tool>` or `info <server>/<tool>`
  306. Workflow:
  307. 1. **Discover**: `mcp-cli info` to see available servers
  308. 2. **Inspect**: `mcp-cli info <server> <tool>` to get the schema
  309. 3. **Execute**: `mcp-cli call <server> <tool> '{}'` with arguments
  310. ### Examples
  311. ```bash
  312. # Call with inline JSON
  313. mcp-cli call github search_repositories '{"query": "mcp server"}'
  314. # Pipe from stdin (no '-' needed)
  315. echo '{"path": "./file"}' | mcp-cli call filesystem read_file
  316. # Heredoc for complex JSON
  317. mcp-cli call server tool <<EOF
  318. {"content": "Text with 'quotes'"}
  319. EOF
  320. ```
  321. ### Common Errors
  322. | Wrong | Error | Fix |
  323. |-------|-------|-----|
  324. | `mcp-cli server tool` | AMBIGUOUS | Use `call server tool` |
  325. | `mcp-cli run server tool` | UNKNOWN_SUBCOMMAND | Use `call` |
  326. | `mcp-cli list` | UNKNOWN_SUBCOMMAND | Use `info` |
  327. ````
  328. ### Option 2: Agents Skill
  329. For Code Agents that support Agents Skills, like Gemini CLI, OpenCode or Claude Code. you can use the mcp-cli skill to interface with MCP servers. The Skill is available at [SKILL.md](./SKILL.md)
  330. Create `mcp-cli/SKILL.md` in your skills directory.
  331. ## Architecture
  332. ### Connection Pooling (Daemon)
  333. By default, the CLI uses **lazy-spawn connection pooling** to avoid repeated MCP server startup latency:
  334. ```
  335. ┌────────────────────────────────────────────────────────────────────┐
  336. │ First CLI Call │
  337. │ $ mcp-cli info server │
  338. └────────────────────────────────────────────────────────────────────┘
  339. │
  340. ▼
  341. ┌────────────────────────────────────────────────────────────────────┐
  342. │ Check: /tmp/mcp-cli-{uid}/server.sock exists? │
  343. └────────────────────────────────────────────────────────────────────┘
  344. │ │
  345. │ NO │ YES
  346. ▼ ▼
  347. ┌─────────────────────────┐ ┌───────────────────────────────────┐
  348. │ Fork background daemon │ │ Connect to existing socket │
  349. │ ├─ Connect to MCP server│ │ ├─ Send request via IPC │
  350. │ ├─ Create Unix socket │ │ ├─ Receive response │
  351. │ └─ Start 60s idle timer │ │ └─ Daemon resets idle timer │
  352. └─────────────────────────┘ └───────────────────────────────────┘
  353. │ │
  354. └────────────────┬───────────────────┘
  355. ▼
  356. ┌────────────────────────────────────────────────────────────────────┐
  357. │ On idle timeout (60s): Daemon self-terminates, cleans up files │
  358. └────────────────────────────────────────────────────────────────────┘
  359. ```
  360. **Key features:**
  361. - **Automatic**: No manual start/stop needed
  362. - **Per-server**: Each MCP server gets its own daemon
  363. - **Stale detection**: Config changes trigger re-spawn
  364. - **Fast fallback**: 5s spawn timeout, then direct connection
  365. **Control via environment:**
  366. ```bash
  367. MCP_NO_DAEMON=1 mcp-cli info # Force fresh connection
  368. MCP_DAEMON_TIMEOUT=120 mcp-cli # 2 minute idle timeout
  369. MCP_DEBUG=1 mcp-cli info # See daemon debug output
  370. ```
  371. ### Connection Model (Direct)
  372. When daemon is disabled (`MCP_NO_DAEMON=1`), the CLI uses a **lazy, on-demand connection strategy**. Server connections are only established when needed and closed immediately after use.
  373. ```
  374. ┌─────────────────────────────────────────────────────────────────┐
  375. │ USER REQUEST │
  376. └─────────────────────────────────────────────────────────────────┘
  377. │
  378. ┌─────────────────┼─────────────────┐
  379. │ │ │
  380. ▼ ▼ ▼
  381. ┌─────────────────┐ ┌─────────────────┐ ┌─────────────────┐
  382. │ mcp-cli info │ │ mcp-cli grep │ │ mcp-cli call │
  383. │ (list all) │ │ "*pattern*" │ │ server tool {} │
  384. └─────────────────┘ └─────────────────┘ └─────────────────┘
  385. │ │ │
  386. ▼ ▼ ▼
  387. ┌─────────────────┐ ┌─────────────────┐ ┌─────────────────┐
  388. │ Connect to ALL │ │ Connect to ALL │ │ Connect to ONE │
  389. │ servers (N) │ │ servers (N) │ │ server only │
  390. └─────────────────┘ └─────────────────┘ └─────────────────┘
  391. │ │ │
  392. ▼ ▼ ▼
  393. List tools Search tools Execute tool
  394. │ │ │
  395. ▼ ▼ ▼
  396. ┌─────────────────────────────────────────────────────────────┐
  397. │ CLOSE CONNECTIONS │
  398. └─────────────────────────────────────────────────────────────┘
  399. ```
  400. **When are servers connected?**
  401. | Command | Servers Connected |
  402. |---------|-------------------|
  403. | `mcp-cli info` | All N servers in parallel |
  404. | `mcp-cli grep "*pattern*"` | All N servers in parallel |
  405. | `mcp-cli info <server>` | Only the specified server |
  406. | `mcp-cli info <server> <tool>` | Only the specified server |
  407. | `mcp-cli call <server> <tool> '{}'` | Only the specified server |
  408. ### Error Handling & Retry
  409. The CLI includes **automatic retry with exponential backoff** for transient failures.
  410. **Transient errors (auto-retried):**
  411. - Network: `ECONNREFUSED`, `ETIMEDOUT`, `ECONNRESET`
  412. - HTTP: `502`, `503`, `504`, `429`
  413. **Non-transient errors (fail immediately):**
  414. - Config: Invalid JSON, missing fields
  415. - Auth: `401`, `403`
  416. - Tool: Validation errors, not found
  417. ## Development
  418. ### Prerequisites
  419. - [Bun](https://bun.sh/) >= 1.0.0
  420. ### Setup
  421. ```bash
  422. bun install https://github.com/philschmid/mcp-cli
  423. ```
  424. ### Commands
  425. ```bash
  426. # Run in development
  427. bun run dev
  428. # Type checking
  429. bun run typecheck
  430. # Linting
  431. bun run lint
  432. bun run lint:fix
  433. # Run all tests (unit + integration)
  434. bun test
  435. # Run only unit tests (fast)
  436. bun test tests/config.test.ts tests/output.test.ts tests/client.test.ts
  437. # Run integration tests (requires MCP server, ~35s)
  438. bun test tests/integration/
  439. # Build single executable
  440. bun run build
  441. # Build for all platforms
  442. bun run build:all
  443. ```
  444. ### Local Testing
  445. Test the CLI locally without compiling by using `bun link`:
  446. ```bash
  447. # Link the package globally (run once)
  448. bun link
  449. # Now you can use 'mcp-cli' anywhere
  450. mcp-cli --help
  451. mcp-cli call filesystem read_file '{"path": "./README.md"}'
  452. # Or run directly during development
  453. bun run dev --help
  454. bun run dev info filesystem
  455. ```
  456. To unlink when done:
  457. ```bash
  458. bun unlink
  459. ```
  460. ### Releasing
  461. Releases are automated via GitHub Actions. Use the release script:
  462. ```bash
  463. ./scripts/release.sh 0.2.0
  464. ```
  465. ### Error Messages
  466. All errors include actionable recovery suggestions, optimized for both humans and AI agents:
  467. ```
  468. Error [AMBIGUOUS_COMMAND]: Ambiguous command: did you mean to call a tool or view info?
  469. Details: Received: mcp-cli filesystem read_file
  470. Suggestion: Use 'mcp-cli call filesystem read_file' to execute, or 'mcp-cli info filesystem read_file' to view schema
  471. Error [UNKNOWN_SUBCOMMAND]: Unknown subcommand: "run"
  472. Details: Valid subcommands: info, grep, call
  473. Suggestion: Did you mean 'mcp-cli call'?
  474. Error [SERVER_NOT_FOUND]: Server "github" not found in config
  475. Details: Available servers: filesystem, sqlite
  476. Suggestion: Use one of: mcp-cli info filesystem, mcp-cli info sqlite
  477. Error [TOOL_NOT_FOUND]: Tool "search" not found in server "filesystem"
  478. Details: Available tools: read_file, write_file, list_directory (+5 more)
  479. Suggestion: Run 'mcp-cli info filesystem' to see all available tools
  480. Error [INVALID_JSON_ARGUMENTS]: Invalid JSON in tool arguments
  481. Details: Parse error: Unexpected identifier "test"
  482. Suggestion: Arguments must be valid JSON. Use single quotes: '{"key": "value"}'
  483. ```
  484. ## License
  485. MIT License - see [LICENSE](LICENSE) for details.
  486. ## Contributing
  487. Contributions are welcome! Please feel free to submit a Pull Request.
install.sh · Bundled script · 176 lines · 1 finding marked
  1. #!/bin/bash
  2. # Install script for mcp-cli
  3. # Usage: curl -fsSL https://raw.githubusercontent.com/philschmid/mcp-cli/main/install.sh | bash
    • Note: Pipes a downloaded script directly into a shell (curl | sh / wget | bash)
    • Line 3 on GitHub
  4. set -e
  5. # Colors
  6. RED='\033[0;31m'
  7. GREEN='\033[0;32m'
  8. YELLOW='\033[1;33m'
  9. BLUE='\033[0;34m'
  10. BOLD='\033[1m'
  11. NC='\033[0m'
  12. # Cleanup on exit
  13. TMP_FILE=""
  14. TMP_CHECKSUM=""
  15. cleanup() {
  16. if [ -n "$TMP_FILE" ] && [ -f "$TMP_FILE" ]; then
  17. rm -f "$TMP_FILE"
  18. fi
  19. if [ -n "$TMP_CHECKSUM" ] && [ -f "$TMP_CHECKSUM" ]; then
  20. rm -f "$TMP_CHECKSUM"
  21. fi
  22. }
  23. trap cleanup EXIT
  24. # Detect OS and architecture
  25. OS=$(uname -s | tr '[:upper:]' '[:lower:]')
  26. ARCH=$(uname -m)
  27. case "$OS" in
  28. linux)
  29. case "$ARCH" in
  30. x86_64) BINARY="mcp-cli-linux-x64" ;;
  31. aarch64) BINARY="mcp-cli-linux-arm64" ;;
  32. *) echo -e "${RED}Unsupported architecture: $ARCH${NC}"; exit 1 ;;
  33. esac
  34. ;;
  35. darwin)
  36. case "$ARCH" in
  37. x86_64) BINARY="mcp-cli-darwin-x64" ;;
  38. arm64) BINARY="mcp-cli-darwin-arm64" ;;
  39. *) echo -e "${RED}Unsupported architecture: $ARCH${NC}"; exit 1 ;;
  40. esac
  41. ;;
  42. *)
  43. echo -e "${RED}Unsupported OS: $OS${NC}"
  44. exit 1
  45. ;;
  46. esac
  47. # Installation directory - prefer ~/.local/bin (no sudo needed)
  48. if [ -z "${INSTALL_DIR:-}" ]; then
  49. if [ -w "/usr/local/bin" ]; then
  50. INSTALL_DIR="/usr/local/bin"
  51. else
  52. INSTALL_DIR="$HOME/.local/bin"
  53. fi
  54. fi
  55. GITHUB_REPO="philschmid/mcp-cli"
  56. # Print banner
  57. echo ""
  58. echo -e "${BOLD}Installing mcp-cli${NC}"
  59. echo ""
  60. echo -e " ${BOLD}Platform${NC}: $OS/$ARCH"
  61. echo -e " ${BOLD}Binary${NC}: $BINARY"
  62. echo -e " ${BOLD}Location${NC}: $INSTALL_DIR/mcp-cli"
  63. echo ""
  64. # Check for existing installation
  65. if command -v mcp-cli &> /dev/null; then
  66. EXISTING_VERSION=$(mcp-cli --version 2>/dev/null || echo "unknown")
  67. echo -e "${YELLOW}Note: Updating existing installation ($EXISTING_VERSION)${NC}"
  68. echo ""
  69. fi
  70. # Get latest release URL
  71. DOWNLOAD_URL="https://github.com/$GITHUB_REPO/releases/latest/download/$BINARY"
  72. CHECKSUM_URL="https://github.com/$GITHUB_REPO/releases/latest/download/checksums.txt"
  73. # Download binary
  74. echo -e "${BLUE}Downloading...${NC}"
  75. TMP_FILE=$(mktemp)
  76. if ! curl -fsSL "$DOWNLOAD_URL" -o "$TMP_FILE"; then
  77. echo -e "${RED}Failed to download binary. Check if releases exist at:${NC}"
  78. echo " https://github.com/$GITHUB_REPO/releases"
  79. exit 1
  80. fi
  81. # Verify checksum (if available)
  82. TMP_CHECKSUM=$(mktemp)
  83. if curl -fsSL "$CHECKSUM_URL" -o "$TMP_CHECKSUM" 2>/dev/null; then
  84. # Extract checksum for our binary
  85. EXPECTED_CHECKSUM=$(grep "$BINARY" "$TMP_CHECKSUM" | awk '{print $1}')
  86. if [ -n "$EXPECTED_CHECKSUM" ]; then
  87. echo -e "${BLUE}Verifying checksum...${NC}"
  88. # Calculate actual checksum
  89. if command -v sha256sum &> /dev/null; then
  90. ACTUAL_CHECKSUM=$(sha256sum "$TMP_FILE" | awk '{print $1}')
  91. elif command -v shasum &> /dev/null; then
  92. ACTUAL_CHECKSUM=$(shasum -a 256 "$TMP_FILE" | awk '{print $1}')
  93. else
  94. echo -e "${YELLOW}Warning: Could not verify checksum (no sha256sum/shasum found)${NC}"
  95. ACTUAL_CHECKSUM=""
  96. fi
  97. if [ -n "$ACTUAL_CHECKSUM" ]; then
  98. if [ "$EXPECTED_CHECKSUM" != "$ACTUAL_CHECKSUM" ]; then
  99. echo -e "${RED}Checksum verification failed!${NC}"
  100. echo "Expected: $EXPECTED_CHECKSUM"
  101. echo "Actual: $ACTUAL_CHECKSUM"
  102. exit 1
  103. fi
  104. echo -e "${GREEN}✓${NC} Checksum verified"
  105. fi
  106. fi
  107. fi
  108. # Make executable
  109. chmod +x "$TMP_FILE"
  110. # Create install directory if needed
  111. if [ ! -d "$INSTALL_DIR" ]; then
  112. echo -e "${BLUE}Creating $INSTALL_DIR...${NC}"
  113. mkdir -p "$INSTALL_DIR"
  114. fi
  115. # Install
  116. echo -e "${BLUE}Installing...${NC}"
  117. if [ -w "$INSTALL_DIR" ]; then
  118. mv "$TMP_FILE" "$INSTALL_DIR/mcp-cli"
  119. else
  120. echo -e "${YELLOW}Requires sudo to install to $INSTALL_DIR${NC}"
  121. sudo mv "$TMP_FILE" "$INSTALL_DIR/mcp-cli"
  122. fi
  123. TMP_FILE="" # Clear so cleanup doesn't try to delete
  124. # Success message
  125. echo ""
  126. echo -e "${GREEN}✓ mcp-cli installed successfully!${NC}"
  127. echo ""
  128. # Check if in PATH and show version
  129. if command -v mcp-cli &> /dev/null; then
  130. mcp-cli --version
  131. else
  132. # Not in PATH - show setup instructions
  133. echo -e "${YELLOW}Add mcp-cli to your PATH:${NC}"
  134. echo ""
  135. SHELL_NAME=$(basename "$SHELL")
  136. case "$SHELL_NAME" in
  137. bash)
  138. echo " echo 'export PATH=\"\$HOME/.local/bin:\$PATH\"' >> ~/.bashrc"
  139. echo " source ~/.bashrc"
  140. ;;
  141. zsh)
  142. echo " echo 'export PATH=\"\$HOME/.local/bin:\$PATH\"' >> ~/.zshrc"
  143. echo " source ~/.zshrc"
  144. ;;
  145. fish)
  146. echo " fish_add_path ~/.local/bin"
  147. ;;
  148. *)
  149. echo " export PATH=\"\$HOME/.local/bin:\$PATH\""
  150. ;;
  151. esac
  152. echo ""
  153. fi
  154. echo "Get started:"
  155. echo " mcp-cli --help"
  156. echo ""

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.