Skip to content
Back to search

mcp2cli

Turn any MCP, OpenAPI, or GraphQL server into a CLI — at runtime, with zero codegen

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/knowsuchagency-mcp2cli/badge.svg)](/listings/knowsuchagency-mcp2cli)

HTML

<a href="/listings/knowsuchagency-mcp2cli"><img src="/api/listings/knowsuchagency-mcp2cli/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.

# Run directly without installing
uvx mcp2cli --help

# Or install globally
uv tool install mcp2cli

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.

README.md · README · 495 lines

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

This file has changed since it was scanned, so this is not exactly the text that was scanned, and no line is marked. The findings are listed with the safety scan above.

  1. <p align="center">
  2. <img src="https://raw.githubusercontent.com/knowsuchagency/mcp2cli/main/assets/hero.png" alt="mcp2cli — one CLI for every API" width="700">
  3. </p>
  4. <h1 align="center">mcp2cli</h1>
  5. <p align="center">
  6. Turn any MCP server, OpenAPI spec, or GraphQL endpoint into a CLI — at runtime, with zero codegen.<br>
  7. <strong>Save 96–99% of the tokens wasted on tool schemas every turn.</strong><br><br>
  8. <a href="https://www.orangecountyai.com/blog/mcp2cli-one-cli-for-every-api-zero-wasted-tokens"><strong>Read the full writeup →</strong></a>
  9. </p>
  10. ## Install
  11. ```bash
  12. # Run directly without installing
  13. uvx mcp2cli --help
  14. # Or install globally
  15. uv tool install mcp2cli
  16. ```
  17. ## AI Agent Skill
  18. mcp2cli ships with an installable [skill](https://skills.sh) that teaches AI coding agents (Claude Code, Cursor, Codex) how to use it. Once installed, your agent can discover and call any MCP server or OpenAPI endpoint — and even generate new skills from APIs.
  19. ```bash
  20. npx skills add knowsuchagency/mcp2cli --skill mcp2cli
  21. ```
  22. After installing, try prompts like:
  23. - `mcp2cli --mcp https://mcp.example.com/sse` — interact with an MCP server
  24. - `mcp2cli create a skill for https://api.example.com/openapi.json` — generate a skill from an API
  25. ## Usage
  26. ### MCP HTTP/SSE mode
  27. ```bash
  28. # Connect to an MCP server over HTTP
  29. mcp2cli --mcp https://mcp.example.com/sse --list
  30. # Call a tool
  31. mcp2cli --mcp https://mcp.example.com/sse search --query "test"
  32. # With auth header
  33. mcp2cli --mcp https://mcp.example.com/sse --auth-header "x-api-key:sk-..." \
  34. query --sql "SELECT 1"
  35. # Force a specific transport (skip streamable HTTP fallback dance)
  36. mcp2cli --mcp https://mcp.example.com/sse --transport sse --list
  37. # Search tools by name or description (case-insensitive substring match)
  38. mcp2cli --mcp https://mcp.example.com/sse --search "task"
  39. ```
  40. `--search` implies `--list` and works across all modes (`--mcp`, `--spec`, `--graphql`, `--mcp-stdio`).
  41. ### OAuth authentication
  42. APIs that require OAuth are supported out of the box — across MCP, OpenAPI, and GraphQL modes.
  43. mcp2cli handles token acquisition, caching, and refresh automatically.
  44. ```bash
  45. # Authorization code + PKCE flow (opens browser for login)
  46. mcp2cli --mcp https://mcp.example.com/sse --oauth --list
  47. mcp2cli --spec https://api.example.com/openapi.json --oauth --list
  48. mcp2cli --graphql https://api.example.com/graphql --oauth --list
  49. # Client credentials flow (machine-to-machine, no browser)
  50. mcp2cli --spec https://api.example.com/openapi.json \
  51. --oauth-client-id "my-client-id" \
  52. --oauth-client-secret "my-secret" \
  53. list-pets
  54. # With specific scopes
  55. mcp2cli --graphql https://api.example.com/graphql --oauth --oauth-scope "read write" users
  56. # Local spec file — use --base-url for OAuth discovery
  57. mcp2cli --spec ./openapi.json --base-url https://api.example.com --oauth --list
  58. ```
  59. Tokens are persisted in `~/.cache/mcp2cli/oauth/` so subsequent calls reuse existing tokens
  60. and refresh automatically when they expire.
  61. #### Headless hosts — no browser on the machine running mcp2cli
  62. The default authorization-code flow starts a callback server on `127.0.0.1`, which only
  63. works when the browser runs on the same machine. On a VPS over SSH or in a container,
  64. add `--oauth-manual-callback`: mcp2cli prints the authorization URL instead of opening a
  65. browser, and reads the redirect back from stdin.
  66. ```bash
  67. mcp2cli --mcp https://mcp.linear.app/mcp --oauth --oauth-manual-callback --list
  68. ```
  69. Open the printed URL in a browser on any machine, authorize, then paste the URL you land
  70. on. That page will fail to load — nothing is listening on the loopback port — which is
  71. expected; only its address matters, because it carries the `code` and `state` parameters.
  72. PKCE and state verification are unchanged, so paste the URL unmodified.
  73. ### Secrets from environment or files
  74. Sensitive values (`--auth-header` values, `--oauth-client-id`, `--oauth-client-secret`) support
  75. `env:` and `file:` prefixes to avoid passing secrets as CLI arguments (which are visible in
  76. process listings):
  77. ```bash
  78. # Read from environment variable
  79. mcp2cli --mcp https://mcp.example.com/sse \
  80. --auth-header "Authorization:env:MY_API_TOKEN" \
  81. --list
  82. # Read from file
  83. mcp2cli --mcp https://mcp.example.com/sse \
  84. --oauth-client-secret "file:/run/secrets/client_secret" \
  85. --oauth-client-id "my-client-id" \
  86. --list
  87. # Works with secret managers that inject env vars
  88. fnox exec -- mcp2cli --mcp https://mcp.example.com/sse \
  89. --oauth-client-id "env:OAUTH_CLIENT_ID" \
  90. --oauth-client-secret "env:OAUTH_CLIENT_SECRET" \
  91. --list
  92. ```
  93. ### MCP stdio mode
  94. ```bash
  95. # List tools from an MCP server
  96. mcp2cli --mcp-stdio "npx @modelcontextprotocol/server-filesystem /tmp" --list
  97. # Call a tool
  98. mcp2cli --mcp-stdio "npx @modelcontextprotocol/server-filesystem /tmp" \
  99. read-file --path /tmp/hello.txt
  100. # Or hand the whole argument object over as JSON, no shell pipe needed
  101. mcp2cli --mcp-stdio "npx @modelcontextprotocol/server-filesystem /tmp" \
  102. read-file --req-json '{"path": "/tmp/hello.txt"}'
  103. # Pass environment variables to the server process
  104. mcp2cli --mcp-stdio "node server.js" --env API_KEY=sk-... --env DEBUG=1 \
  105. search --query "test"
  106. ```
  107. ### Raw tool definitions (`--schema`)
  108. `--list` shows a token-cheap, flattened view of each tool's parameters. When you
  109. need the exact wire contract — nested objects, `anyOf` branches, `default`,
  110. `outputSchema` — ask for the raw definition instead:
  111. ```bash
  112. # Global form: wire name, or the kebab-case name shown by --list
  113. mcp2cli --mcp https://example.com/mcp --schema getUserProfile
  114. mcp2cli --mcp https://example.com/mcp --schema get-user-profile
  115. # After the tool name, including inside a session
  116. mcp2cli --mcp https://example.com/mcp get-user-profile --schema
  117. mcp2cli --session work get-user-profile --schema
  118. ```
  119. The output is the server's own `tools/list` entry. Property names such as
  120. `fooBar` stay `fooBar`, and `inputSchema` / `outputSchema` / `annotations` keep
  121. their wire spelling — nothing is renamed or flattened.
  122. Only MCP sources support `--schema`; `--spec` and `--graphql` reject it.
  123. A tool with its own `schema` parameter keeps `--schema` for that parameter, so
  124. use the global form (`--schema TOOL`) to see its definition.
  125. ### MCP roots and completion
  126. Expose one or more filesystem roots when a server scopes operations to a
  127. workspace. Paths are converted to `file://` URIs; explicit roots must also use
  128. the `file://` scheme.
  129. ```bash
  130. mcp2cli --mcp-stdio "npx @modelcontextprotocol/server-filesystem /tmp" \
  131. --root "$PWD" --root file:///var/shared --list
  132. ```
  133. Request prompt-argument or resource-template completions with
  134. `REF:ARG=PREFIX`:
  135. ```bash
  136. mcp2cli --mcp https://example.com/mcp \
  137. --complete "greeting:name=San"
  138. mcp2cli --mcp https://example.com/mcp \
  139. --complete "file:///docs/{topic}:topic=api"
  140. ```
  141. Both options work when starting a persistent session; roots are retained by
  142. the session daemon and completion requests can be sent through `--session`.
  143. ### Sessions — reuse one MCP connection
  144. A one-shot call pays for starting the server and running `initialize` every
  145. time. A named session keeps one daemon — and one MCP connection — alive and
  146. routes later calls to it.
  147. ```bash
  148. # Start a daemon that owns the connection
  149. mcp2cli --session-start work --mcp-stdio "npx @modelcontextprotocol/server-filesystem ."
  150. # Call tools through it — no reconnect, no re-initialize
  151. mcp2cli --session work --list
  152. mcp2cli --session work read-file --path ./README.md
  153. # Inspect and stop
  154. mcp2cli --session-list
  155. mcp2cli --session-stop work
  156. ```
  157. Sessions live under `~/.cache/mcp2cli/sessions` (override with
  158. `MCP2CLI_CACHE_DIR`). The daemon is detached from the shell that started it,
  159. so closing that terminal does not end the session.
  160. How a client reaches the daemon depends on the platform:
  161. | Platform | Transport | Notes |
  162. |---|---|---|
  163. | macOS, Linux | Unix domain socket (`<name>.sock`) | `sessions/` is `0700`, metadata `0600` |
  164. | Windows | Loopback TCP on `127.0.0.1` | Windows CPython has no `socket.AF_UNIX` |
  165. Every request carries a per-session token that the daemon generates on start,
  166. so another local process cannot drive your session by connecting to its port.
  167. `--session-stop` asks the daemon to exit over that same channel, which lets it
  168. close the MCP server cleanly and delete its own files. Set
  169. `MCP2CLI_SESSION_TRANSPORT=unix|tcp` to pin a transport instead of taking the
  170. platform default.
  171. ### OpenAPI mode
  172. ```bash
  173. # List all commands from a remote spec
  174. mcp2cli --spec https://petstore3.swagger.io/api/v3/openapi.json --list
  175. # Call an endpoint
  176. mcp2cli --spec ./openapi.json --base-url https://api.example.com list-pets --status available
  177. # With auth
  178. mcp2cli --spec ./spec.json --auth-header "Authorization:Bearer tok_..." create-item --name "Test"
  179. # POST with a JSON body given inline
  180. mcp2cli --spec ./spec.json create-pet --req-json '{"name": "Fido", "tag": "dog"}'
  181. # ...or piped to stdin
  182. echo '{"name": "Fido", "tag": "dog"}' | mcp2cli --spec ./spec.json create-pet --stdin
  183. # Flags given with --req-json/--stdin are merged into the JSON (a conflicting value is an error)
  184. echo '{"name": "Fido"}' | mcp2cli --spec ./spec.json create-pet --tag dog --stdin
  185. # Local YAML spec
  186. mcp2cli --spec ./api.yaml --base-url http://localhost:8000 --list
  187. ```
  188. ### GraphQL mode
  189. ```bash
  190. # List all queries and mutations from a GraphQL endpoint
  191. mcp2cli --graphql https://api.example.com/graphql --list
  192. # Call a query
  193. mcp2cli --graphql https://api.example.com/graphql users --limit 10
  194. # Call a mutation
  195. mcp2cli --graphql https://api.example.com/graphql create-user --name "Alice" --email "alice@example.com"
  196. # Override auto-generated selection set fields
  197. mcp2cli --graphql https://api.example.com/graphql --fields "id name email" users
  198. # With auth
  199. mcp2cli --graphql https://api.example.com/graphql --auth-header "Authorization:Bearer tok_..." users
  200. ```
  201. mcp2cli introspects the endpoint, discovers queries and mutations, auto-generates selection sets, and constructs parameterized queries with proper variable declarations. No SDL parsing, no code generation — just point and run.
  202. ### Bake mode — save connection settings
  203. Tired of repeating `--spec`/`--mcp`/`--mcp-stdio` plus auth flags on every invocation? Bake them into a named configuration:
  204. ```bash
  205. # Create a baked tool from an OpenAPI spec
  206. mcp2cli bake create petstore --spec https://api.example.com/spec.json \
  207. --exclude "delete-*,update-*" --methods GET,POST --cache-ttl 7200
  208. # Create a baked tool from an MCP stdio server
  209. mcp2cli bake create myfs --mcp-stdio "npx -y @modelcontextprotocol/server-filesystem /tmp" \
  210. --include "search-*,list-*" --exclude "list-allowed-*"
  211. # Use a baked tool with @ prefix — no connection flags needed
  212. mcp2cli @petstore --list
  213. mcp2cli @petstore list-pets --limit 10
  214. mcp2cli @myfs --list # search-files, list-directory, list-directory-with-sizes
  215. mcp2cli @myfs search-files --path /tmp --pattern "**/*.md" # pattern is a glob, relative to --path
  216. # Manage baked tools
  217. mcp2cli bake list # show all baked tools
  218. mcp2cli bake show petstore # show config (secrets masked)
  219. mcp2cli bake update petstore --cache-ttl 3600
  220. mcp2cli bake remove petstore
  221. mcp2cli bake install petstore # creates ~/.local/bin/petstore wrapper
  222. mcp2cli bake install petstore --dir ./scripts/ # install wrapper to custom directory
  223. ```
  224. Filtering options:
  225. - `--include` — comma-separated glob patterns to whitelist tools (e.g. `"list-*,get-*"`)
  226. - `--exclude` — comma-separated glob patterns to blacklist tools (e.g. `"delete-*"`)
  227. - `--methods` — comma-separated HTTP methods to allow (e.g. `"GET,POST"`, OpenAPI only)
  228. Configs are stored in `~/.config/mcp2cli/baked.json`. Override with `MCP2CLI_CONFIG_DIR`.
  229. `bake show` masks the credential values it knows about — the OAuth client secret and every `--auth-header` value — while leaving `env:`/`file:` references readable so the config stays diagnosable. Values baked in with `--env` are printed as stored, so scrub those before pasting the output if an env var carries a token.
  230. ### Usage-aware tool ranking
  231. mcp2cli tracks tool invocations locally and uses that data to rank `--list` output, reducing token costs for LLM agents working with large servers.
  232. ```bash
  233. # Default --list: ~1,400 tokens for 96 tools
  234. mcp2cli @myapi --list
  235. # Top 10 most-used tools, names only: ~20 tokens
  236. mcp2cli @myapi --list --top 10 --compact
  237. # Sort by most recently used
  238. mcp2cli @myapi --list --sort recent
  239. # Alphabetical sort
  240. mcp2cli @myapi --list --sort alpha
  241. ```
  242. When usage data exists for a source, `--list` defaults to sorting by call frequency. Otherwise insertion order is preserved. Usage data is stored in `~/.cache/mcp2cli/usage.json`.
  243. ### JSON output
  244. `--json` forces **valid JSON on stdout for every command**, in every mode. It is the
  245. machine-readable counterpart to the human-formatted default output, designed for LLM
  246. agents and scripts that need to parse results reliably.
  247. ```bash
  248. # --list emits a JSON array of command objects (name, description, parameters, ...)
  249. mcp2cli --mcp https://mcp.example.com/sse --list --json
  250. mcp2cli --spec ./openapi.json --list --json
  251. mcp2cli --graphql https://api.example.com/graphql --list --json
  252. # --list --json --compact emits a JSON array of names only
  253. mcp2cli --mcp https://mcp.example.com/sse --list --json --compact
  254. # MCP tool calls emit the FULL CallToolResult envelope — including
  255. # structuredContent and isError, not just the flattened text. This surfaces the
  256. # machine-readable result that modern MCP tools put in structuredContent.
  257. mcp2cli --mcp https://mcp.example.com/sse --json search --query "test"
  258. # { "content": [...], "structuredContent": {...}, "isError": false }
  259. # OpenAPI / GraphQL calls emit the response as JSON (non-JSON bodies become a JSON string)
  260. mcp2cli --spec ./openapi.json --json list-pets
  261. mcp2cli --graphql https://api.example.com/graphql --json users
  262. ```
  263. `--json` takes precedence over `--raw` and `--toon` (both of which can produce
  264. non-JSON), so it always wins — that is what makes it a reliable "force JSON" switch.
  265. Indentation follows the usual rule: pretty on a TTY or with `--pretty`, compact when piped.
  266. ### Output control
  267. ```bash
  268. # Pretty-print JSON (also auto-enabled for TTY)
  269. mcp2cli --spec ./spec.json --pretty list-pets
  270. # Raw response body (no JSON parsing)
  271. mcp2cli --spec ./spec.json --raw get-data
  272. # Truncate large responses to first N records
  273. mcp2cli --spec ./spec.json --head 5 list-records
  274. # Pipe-friendly (compact JSON when not a TTY)
  275. mcp2cli --spec ./spec.json list-pets | jq '.[] | .name'
  276. # TOON output — token-efficient encoding for LLM consumption
  277. # Best for large uniform arrays (40-60% fewer tokens than JSON)
  278. mcp2cli --mcp https://mcp.example.com/sse --toon list-tags
  279. ```
  280. ### Caching
  281. Specs and MCP tool lists are cached in `~/.cache/mcp2cli/` with a 1-hour TTL by default.
  282. ```bash
  283. # Force refresh
  284. mcp2cli --spec https://api.example.com/spec.json --refresh --list
  285. # Custom TTL (seconds)
  286. mcp2cli --spec https://api.example.com/spec.json --cache-ttl 86400 --list
  287. # Custom cache key
  288. mcp2cli --spec https://api.example.com/spec.json --cache-key my-api --list
  289. # Override cache directory
  290. MCP2CLI_CACHE_DIR=/tmp/my-cache mcp2cli --spec ./spec.json --list
  291. ```
  292. Local file specs are never cached.
  293. ## CLI reference
  294. ```
  295. mcp2cli [global options] <subcommand> [command options]
  296. Source (mutually exclusive, one required):
  297. --spec URL|FILE OpenAPI spec (JSON or YAML, local or remote)
  298. --mcp URL MCP server URL (HTTP/SSE)
  299. --mcp-stdio CMD MCP server command (stdio transport)
  300. --graphql URL GraphQL endpoint URL
  301. Options:
  302. --auth-header K:V HTTP header (repeatable, value supports env:/file: prefixes)
  303. --base-url URL Override base URL from spec
  304. --transport TYPE MCP HTTP transport: auto|sse|streamable (default: auto)
  305. --env KEY=VALUE Env var for MCP stdio server (repeatable)
  306. --root PATH|FILE_URI Expose a filesystem root to an MCP server (repeatable)
  307. --complete SPEC Complete an MCP prompt or resource-template argument
  308. --oauth Enable OAuth (authorization code + PKCE flow)
  309. --oauth-client-id ID OAuth client ID (supports env:/file: prefixes)
  310. --oauth-client-secret S OAuth client secret (supports env:/file: prefixes)
  311. --oauth-scope SCOPE OAuth scope(s) to request
  312. --oauth-manual-callback Print the auth URL and read the redirect from stdin
  313. (for hosts with no reachable browser)
  314. --cache-key KEY Custom cache key
  315. --cache-ttl SECONDS Cache TTL (default: 3600)
  316. --refresh Bypass cache
  317. --list List available subcommands
  318. --search PATTERN Search tools by name or description (implies --list)
  319. --schema TOOL Print one MCP tool's raw definition (inputSchema,
  320. outputSchema, annotations) with wire names preserved
  321. --sort MODE Sort --list output: usage|recent|alpha|default
  322. --top N Show only the top N tools in --list output
  323. --compact Space-separated tool names only, no descriptions
  324. --verbose Show full tool descriptions (unwrapped)
  325. --fields FIELDS Override GraphQL selection set (e.g. "id name email")
  326. --pretty Pretty-print JSON output
  327. --raw Print raw response body
  328. --json Force valid JSON output for every command (--list and tool
  329. calls). MCP calls emit the full result envelope including
  330. structuredContent. Takes precedence over --raw and --toon.
  331. --toon Encode output as TOON (token-efficient for LLMs)
  332. --head N Limit output to first N records (arrays)
  333. --version Show version
  334. Bake mode:
  335. bake create NAME [opts] Save connection settings as a named tool
  336. bake list List all baked tools
  337. bake show NAME Show config (secrets masked)
  338. bake update NAME [opts] Update a baked tool
  339. bake remove NAME Delete a baked tool
  340. bake install NAME Create ~/.local/bin wrapper script
  341. @NAME [args] Run a baked tool (e.g. mcp2cli @petstore --list)
  342. ```
  343. Subcommands and their flags are generated dynamically from the spec or MCP server tool definitions. Run `<subcommand> --help` for details.
  344. > For token savings analysis, architecture details, and comparison to Anthropic's Tool Search, see the **[full writeup on the OCAI blog](https://www.orangecountyai.com/blog/mcp2cli-one-cli-for-every-api-zero-wasted-tokens)**.
  345. ## Development
  346. ```bash
  347. # Install with test + MCP deps
  348. uv sync --extra test
  349. # Run tests
  350. uv run pytest tests/ -v
  351. # Run just the token savings tests
  352. uv run pytest tests/test_token_savings.py -v -s
  353. ```
  354. ### MCP SDK compatibility
  355. mcp2cli works with **both major versions** of the MCP Python SDK (`mcp>=1.26,<3`),
  356. so it never forces a resolver conflict with other tools in the same environment.
  357. CI runs the suite against the declared floor, the latest 1.x, and the latest 2.x.
  358. The two majors differ in ways that matter to a client — v2 renamed model fields
  359. to snake_case, replaced `streamablehttp_client`, moved to `httpx2`, and dropped
  360. the session-id element from the transport tuple. Those differences are confined
  361. to a handful of helpers (`_mcp_attr`, `_mcp_dump`, `_streamable_streams`,
  362. `_list_tools_page`, `_resource_uri`, `_authorization_code_result`); the rest of
  363. the codebase is version-agnostic. The test fixtures speak the JSON-RPC wire
  364. protocol directly and import no SDK, so they hold across majors.
  365. ---
  366. ## License
  367. [MIT](LICENSE)

Ratings and comments

Sign in to rate this skill.

Sign in

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