Skip to content
Back to search

mcptools

A command-line interface for interacting with MCP (Model Context Protocol) servers using both stdio and HTTP transport.

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

HTML

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

Using Homebrew (for macOS)

brew tap f/mcptools
brew install mcp

> ❕ The binary is installed as `mcp` but can also be accessed as `mcpt` to avoid conflicts with other tools that might use the `mcp` command name.

From Source (for Windows and GNU/Linux)

go install github.com/f/mcptools/cmd/mcptools@latest

> ❕ The binary will be installed as `mcptools` when but can be aliased to `mcpt` for convenience. > > <img width="500" alt="Screenshot 2025-05-05 at 22 21 29" src="https://github.com/user-attachments/assets/eaba88c1-8833-4525-bb19-9ab0ec2ff27e" /> > > <sub>Windows 11 Running Example</sub>

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 · 892 lines

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

  1. <p align="center">
  2. <img src="./.github/resources/logo.png" alt="MCP Tools" height="150">
  3. </p>
  4. <p align="center">
  5. <h1 align="center">Swiss Army Knife for MCP Servers</h1>
  6. <p align="center">
  7. A comprehensive command-line interface for interacting with MCP (Model Context Protocol) servers.
  8. <br>
  9. Discover, call, and manage tools, resources, and prompts from any MCP-compatible server.
  10. <br>
  11. Supports multiple transport methods, output formats, and includes powerful mock and proxy server capabilities.
  12. </p>
  13. </p>
  14. [![Blog Post](https://img.shields.io/badge/Blog-Read%20about%20MCP%20Tools-blue)](https://blog.fka.dev/blog/2025-03-27-mcp-inspector-vs-mcp-tools/)
  15. ## Table of Contents
  16. - [Overview](#overview)
  17. - [Difference Between the MCP Inspector and MCP Tools](https://blog.fka.dev/blog/2025-03-27-mcp-inspector-vs-mcp-tools/)
  18. - [Installation](#installation)
  19. - [Using Homebrew](#using-homebrew)
  20. - [From Source](#from-source)
  21. - [Getting Started](#getting-started)
  22. - [Features](#features)
  23. - [Transport Options](#transport-options)
  24. - [Output Formats](#output-formats)
  25. - [Commands](#commands)
  26. - [Interactive Shell](#interactive-shell)
  27. - [Web Interface](#web-interface)
  28. - [Project Scaffolding](#project-scaffolding)
  29. - [Server Aliases](#server-aliases)
  30. - [LLM Apps Config Management](#llm-apps-config-management)
  31. - [Server Modes](#server-modes)
  32. - [Mock Server Mode](#mock-server-mode)
  33. - [Proxy Mode](#proxy-mode)
  34. - [Guard Mode](#guard-mode)
  35. - [Examples](#examples)
  36. - [Basic Usage](#basic-usage)
  37. - [Script Integration](#script-integration)
  38. - [Debugging](#debugging)
  39. - [Contributing](#contributing)
  40. - [Roadmap](#roadmap)
  41. - [License](#license)
  42. ## Overview
  43. MCP Tools provides a versatile CLI for working with Model Context Protocol (MCP) servers. It enables you to:
  44. - Discover and call tools provided by MCP servers
  45. - Access and utilize resources exposed by MCP servers
  46. - Create mock servers for testing client applications
  47. - Proxy MCP requests to shell scripts for easy extensibility
  48. - Create interactive shells for exploring and using MCP servers
  49. - Scaffold new MCP projects with TypeScript support
  50. - Format output in various styles (JSON, pretty-printed, table)
  51. - Guard and restrict access to specific tools and resources
  52. - Support all transport methods (HTTP, stdio)
  53. <p align="center">
  54. <img src=".github/resources/screenshot.png" alt="MCP Tools Screenshot" width="700">
  55. </p>
  56. ## Installation
  57. ### Using Homebrew (for macOS)
  58. ```bash
  59. brew tap f/mcptools
  60. brew install mcp
  61. ```
  62. > ❕ The binary is installed as `mcp` but can also be accessed as `mcpt` to avoid conflicts with other tools that might use the `mcp` command name.
  63. ### From Source (for Windows and GNU/Linux)
  64. ```bash
  65. go install github.com/f/mcptools/cmd/mcptools@latest
  66. ```
  67. > ❕ The binary will be installed as `mcptools` when but can be aliased to `mcpt` for convenience.
  68. >
  69. > <img width="500" alt="Screenshot 2025-05-05 at 22 21 29" src="https://github.com/user-attachments/assets/eaba88c1-8833-4525-bb19-9ab0ec2ff27e" />
  70. >
  71. > <sub>Windows 11 Running Example</sub>
  72. ## Getting Started
  73. The simplest way to start using MCP Tools is to connect to an MCP server and list available tools:
  74. ```bash
  75. # List all available tools from a filesystem server
  76. mcp tools npx -y @modelcontextprotocol/server-filesystem ~
  77. # Call a specific tool
  78. mcp call read_file --params '{"path":"README.md"}' npx -y @modelcontextprotocol/server-filesystem ~
  79. # Open an interactive shell
  80. mcp shell npx -y @modelcontextprotocol/server-filesystem ~
  81. ```
  82. ## Features
  83. MCP Tools supports a wide range of features for interacting with MCP servers:
  84. ```
  85. Usage:
  86. mcp [command]
  87. Available Commands:
  88. version Print the version information
  89. tools List available tools on the MCP server
  90. resources List available resources on the MCP server
  91. prompts List available prompts on the MCP server
  92. call Call a tool, resource, or prompt on the MCP server
  93. get-prompt Get a prompt on the MCP server
  94. read-resource Read a resource on the MCP server
  95. shell Start an interactive shell for MCP commands
  96. web Start a web interface for MCP commands
  97. mock Create a mock MCP server with tools, prompts, and resources
  98. proxy Proxy MCP tool requests to shell scripts
  99. alias Manage MCP server aliases
  100. configs Manage MCP server configurations
  101. new Create a new MCP project component
  102. help Help about any command
  103. completion Generate the autocompletion script for the specified shell
  104. Flags:
  105. -f, --format string Output format (table, json, pretty) (default "table")
  106. -h, --help help for mcp
  107. -p, --params string JSON string of parameters to pass to the tool (for call command) (default "{}")
  108. Use "mcp [command] --help" for more information about a command.
  109. ```
  110. ### Transport Options
  111. MCP Tools supports multiple transport methods for communicating with MCP servers:
  112. #### Stdio Transport
  113. Uses stdin/stdout to communicate with an MCP server via JSON-RPC 2.0. This is useful for command-line tools that implement the MCP protocol.
  114. ```bash
  115. mcp tools npx -y @modelcontextprotocol/server-filesystem ~
  116. ```
  117. #### HTTP SSE Transport
  118. Uses HTTP and Server-Sent Events (SSE) to communicate with an MCP server via JSON-RPC 2.0. This is useful for connecting to remote servers that implement the legacy MCP protocol. Transport is automatically detected when the URL ends with `/sse`.
  119. ```bash
  120. mcp tools http://localhost:3001/sse
  121. # Example: Use the everything sample server
  122. # docker run -p 3001:3001 --rm -it tzolov/mcp-everything-server:v1
  123. ```
  124. _Note:_ HTTP SSE currently supports only MCP protocol version 2024-11-05.
  125. #### Streamable HTTP Transport (Recommended)
  126. Uses streamable HTTP to communicate with an MCP server via JSON-RPC 2.0. This is the modern, recommended approach for connecting to remote servers that implement the MCP protocol. It supports both streaming responses and simple request/response patterns. This is the default transport for HTTP/HTTPS URLs.
  127. ```bash
  128. # Default transport for HTTP URLs
  129. mcp tools http://localhost:3000
  130. # Streamable HTTP transport (auto-detected from URL)
  131. mcp tools http://localhost:3000
  132. # Examples with remote servers
  133. mcp tools https://api.example.com/mcp
  134. mcp tools https://ne.tools
  135. ```
  136. _Benefits of Streamable HTTP:_
  137. - **Session Management**: Supports stateful connections with session IDs
  138. - **Resumability**: Can reconnect and resume interrupted sessions (when supported by server)
  139. - **Flexible Responses**: Supports both streaming and direct JSON responses
  140. - **Modern Protocol**: Uses the latest MCP transport specification
  141. ### Output Formats
  142. MCP Tools supports three output formats to accommodate different needs:
  143. #### Table Format (Default)
  144. ```bash
  145. mcp tools npx -y @modelcontextprotocol/server-filesystem ~
  146. ```
  147. The default format now displays tools in a colorized man-page style:
  148. ```
  149. read_file(path:str)
  150. Read the complete contents of a file from the file system.
  151. read_multiple_files(paths:str[])
  152. Read the contents of multiple files simultaneously.
  153. list_dir(path:str)
  154. Lists the contents of a directory.
  155. write_file(path:str, content:str)
  156. Writes content to a file.
  157. grep_search(pattern:str, [excludePatterns:str[]])
  158. Search files with pattern.
  159. edit_file(edits:{newText:str,oldText:str}[], path:str)
  160. Edit a file with multiple text replacements
  161. ```
  162. Key features of the format:
  163. - Function names are displayed in bold cyan
  164. - Required parameters are shown in green (e.g., `path:str`)
  165. - Optional parameters are shown in yellow brackets (e.g., `[limit:int]`)
  166. - Array types are indicated with `[]` suffix (e.g., `str[]`)
  167. - Object types show their properties in curly braces (e.g., `{prop1:type1,prop2:type2}`)
  168. - Nested objects are displayed recursively (e.g., `{notifications:{enabled:bool,sound:bool}}`)
  169. - Type names are shortened for readability (e.g., `str` instead of `string`, `int` instead of `integer`)
  170. - Descriptions are indented and displayed in gray
  171. - Parameter order is consistent, with required parameters listed first
  172. #### JSON Format (Compact)
  173. ```bash
  174. mcp tools --format json npx -y @modelcontextprotocol/server-filesystem ~
  175. ```
  176. #### Pretty JSON Format (Indented)
  177. ```bash
  178. mcp tools --format pretty npx -y @modelcontextprotocol/server-filesystem ~
  179. ```
  180. ### Commands
  181. MCP Tools includes several core commands for interacting with MCP servers:
  182. #### List Available Tools
  183. ```bash
  184. mcp tools npx -y @modelcontextprotocol/server-filesystem ~
  185. ```
  186. #### List Available Resources
  187. ```bash
  188. mcp resources npx -y @modelcontextprotocol/server-filesystem ~
  189. ```
  190. #### List Available Prompts
  191. ```bash
  192. mcp prompts npx -y @modelcontextprotocol/server-filesystem ~
  193. ```
  194. #### Call a Tool
  195. ```bash
  196. mcp call read_file --params '{"path":"/path/to/file"}' npx -y @modelcontextprotocol/server-filesystem ~
  197. ```
  198. #### Call a Resource
  199. ```bash
  200. mcp call resource:test://static/resource/1 npx -y @modelcontextprotocol/server-everything -f json | jq ".contents[0].text"
  201. ```
  202. or
  203. ```bash
  204. mcp read-resource test://static/resource/1 npx -y @modelcontextprotocol/server-everything -f json | jq ".contents[0].text"
  205. ```
  206. #### Call a Prompt
  207. ```bash
  208. mcp get-prompt simple_prompt npx -y @modelcontextprotocol/server-everything -f json | jq ".messages[0].content.text"
  209. ```
  210. #### Viewing Server Logs
  211. When using client commands that make calls to the server, you can add the `--server-logs` flag to see the server logs related to your request:
  212. ```bash
  213. # View server logs when listing tools
  214. mcp tools --server-logs npx -y @modelcontextprotocol/server-filesystem ~
  215. ```
  216. Output:
  217. ```
  218. [>] Secure MCP Filesystem Server running on stdio
  219. [>] Allowed directories: [ '/Users/fka/' ]
  220. read_file(path:str)
  221. Read the complete contents of a file from the file system.
  222. read_multiple_files(paths:str[])
  223. Read the contents of multiple files simultaneously.
  224. ... and the other tools available on this server
  225. ```
  226. This can be helpful for debugging or understanding what's happening on the server side when executing these commands.
  227. ### Interactive Shell
  228. The interactive shell mode allows you to run multiple MCP commands in a single session:
  229. ```bash
  230. mcp shell npx -y @modelcontextprotocol/server-filesystem ~
  231. ```
  232. This opens an interactive shell with the following capabilities:
  233. ```
  234. mcp tools shell
  235. connected to: npx -y @modelcontextprotocol/server-filesystem /Users/fka
  236. mcp > Type '/h' for help or '/q' to quit
  237. mcp > tools
  238. read_file(path:str, [limit:int], [offset:int])
  239. Reads a file from the filesystem
  240. list_dir(path:str)
  241. Lists directory contents
  242. grep_search(pattern:str, [excludePatterns:str[]])
  243. Search files with pattern
  244. edit_file(edits:{newText:str,oldText:str}[], path:str)
  245. Edit a file with multiple text replacements
  246. # Direct tool calling is supported
  247. mcp > read_file {"path":"README.md"}
  248. ...content of README.md...
  249. # Calling a tool with complex object parameters
  250. mcp > edit_file {"path":"main.go","edits":[{"oldText":"foo","newText":"bar"}]}
  251. ...result of edit operation...
  252. # Get help
  253. mcp > /h
  254. MCP Shell Commands:
  255. tools List available tools
  256. resources List available resources
  257. prompts List available prompts
  258. call <entity> [--params '{...}'] Call a tool, resource, or prompt
  259. format [json|pretty|table] Get or set output format
  260. Special Commands:
  261. /h, /help Show this help
  262. /q, /quit, exit Exit the shell
  263. ```
  264. ### Web Interface
  265. MCP Tools provides a web interface for interacting with MCP servers through a browser-based UI:
  266. ```bash
  267. # Start a web interface for a filesystem server on default port (41999)
  268. mcp web npx -y @modelcontextprotocol/server-filesystem ~
  269. # Use a custom port
  270. mcp web --port 8080 docker run -i --rm -e GITHUB_PERSONAL_ACCESS_TOKEN ghcr.io/github/github-mcp-server
  271. # Use SSE
  272. mcp web https://ne.tools
  273. ```
  274. The web interface includes:
  275. - A sidebar listing all available tools, resources, and prompts
  276. - Form-based and JSON-based parameter editing
  277. - Formatted and raw JSON response views
  278. - Interactive parameter forms automatically generated from tool schemas
  279. - Support for complex parameter types (arrays, objects, nested structures)
  280. - Direct API access for tool calling
  281. Once started, you can access the interface by opening `http://localhost:41999` (or your custom port) in a browser.
  282. <p align="center">
  283. <img src=".github/resources/web-interface.png" alt="MCP Web Interface" width="700">
  284. </p>
  285. ### Project Scaffolding
  286. MCP Tools provides a scaffolding feature to quickly create new MCP servers with TypeScript:
  287. ```bash
  288. mkdir my-mcp-server
  289. cd my-mcp-server
  290. # Create a project with specific components
  291. mcp new tool:calculate resource:file prompt:greet
  292. # Create a project with a specific SDK (currently only TypeScript/ts supported)
  293. mcp new tool:calculate --sdk=ts
  294. # Create a project with a specific transport type
  295. mcp new tool:calculate --transport=stdio
  296. mcp new tool:calculate --transport=sse
  297. ```
  298. The scaffolding creates a complete project structure with:
  299. - Server setup with chosen transport (stdio or SSE)
  300. - TypeScript configuration with modern ES modules
  301. - Component implementations with proper MCP interfaces
  302. - Automatic wiring of imports and initialization
  303. After scaffolding, you can build and run your MCP server:
  304. ```bash
  305. # Install dependencies
  306. npm install
  307. # Build the TypeScript code
  308. npm run build
  309. # Test the server with MCP Tools
  310. mcp tools node build/index.js
  311. ```
  312. Project templates are stored in either:
  313. - Local `./templates/` directory
  314. - User's home directory: `~/.mcpt/templates/`
  315. - Homebrew installation path (`/opt/homebrew/Cellar/mcp/v#.#.#/templates`)
  316. When installing via Homebrew, templates are automatically installed to your home directory. But if you use source install, you need to run `make install-templates`.
  317. ## Server Aliases
  318. MCP Tools allows you to save and reuse server commands with friendly aliases:
  319. ```bash
  320. # Add a new server alias
  321. mcp alias add myfs npx -y @modelcontextprotocol/server-filesystem ~/
  322. # List all registered server aliases
  323. mcp alias list
  324. # Remove a server alias
  325. mcp alias remove myfs
  326. # Use an alias with any MCP command
  327. mcp tools myfs
  328. mcp call read_file --params '{"path":"README.md"}' myfs
  329. ```
  330. Server aliases are stored in `$HOME/.mcpt/aliases.json` and provide a convenient way to work with commonly used MCP servers without typing long commands repeatedly.
  331. ## LLM Apps Config Management
  332. MCP Tools provides a powerful configuration management system that helps you work with MCP server configurations across multiple applications:
  333. > 🚧 This works only on macOS for now.
  334. ```bash
  335. # Scan for MCP server configurations across all supported applications
  336. mcp configs scan
  337. # List all configurations (alias for configs view --all)
  338. mcp configs ls
  339. # View specific configuration by alias
  340. mcp configs view vscode
  341. # Add or update a server in a configuration
  342. mcp configs set vscode my-server npm run mcp-server
  343. mcp configs set cursor my-api https://api.example.com/mcp --headers "Authorization=Bearer token"
  344. # Add to multiple configurations at once
  345. mcp configs set vscode,cursor,claude-desktop my-server npm run mcp-server
  346. # Remove a server from a configuration
  347. mcp configs remove vscode my-server
  348. # Create an alias for a custom config file
  349. mcp configs alias myapp ~/myapp/config.json
  350. # Synchronize and merge configurations from multiple sources
  351. mcp configs sync vscode cursor --output vscode --default interactive
  352. # Convert a command line to MCP server JSON configuration format
  353. mcp configs as-json mcp proxy start
  354. # Output: {"command":"mcp","args":["proxy","start"]}
  355. # Convert a URL to MCP server JSON configuration format
  356. mcp configs as-json https://api.example.com/mcp --headers "Authorization=Bearer token"
  357. # Output: {"url":"https://api.example.com/mcp","headers":{"Authorization":"Bearer token"}}
  358. ```
  359. Configurations are managed through a central registry in `$HOME/.mcpt/configs.json` with predefined aliases for:
  360. - VS Code and VS Code Insiders
  361. - Windsurf
  362. - Cursor
  363. - Claude Desktop and Claude Code
  364. The system automatically displays server configurations in a colorized format grouped by source, showing command-line or URL information, headers, and environment variables.
  365. `mcp configs scan` command looks for MCP server configurations in:
  366. - Visual Studio Code
  367. - Visual Studio Code Insiders
  368. - Windsurf
  369. - Cursor
  370. - Claude Desktop
  371. Example Output:
  372. ```
  373. VS Code Insiders
  374. GitHub (stdio):
  375. docker run -i --rm -e GITHUB_PERSONAL_ACCESS_TOKEN ghcr.io/github/github-mcp-server
  376. Claude Desktop
  377. Proxy (stdio):
  378. mcp proxy start
  379. My Files (stdio):
  380. npx -y @modelcontextprotocol/server-filesystem ~/
  381. ```
  382. ### Bonus
  383. Add official GitHub MCP Server to Windsurf, Cursor and VS Code at once:
  384. ```bash
  385. mcp configs set windsurf,cursor,vscode GitHub \
  386. --env "GITHUB_PERSONAL_ACCESS_TOKEN=github_pat_xxx" \
  387. docker run -i --rm -e GITHUB_PERSONAL_ACCESS_TOKEN ghcr.io/github/github-mcp-server
  388. ```
  389. <p align="center">
  390. <img src=".github/resources/configs.png" alt="MCP Configs Screenshot" width="700">
  391. </p>
  392. ## Server Modes
  393. MCP Tools can operate as both a client and a server, with two server modes available:
  394. ### Mock Server Mode
  395. The mock server mode creates a simulated MCP server for testing clients without implementing a full server:
  396. ```bash
  397. # Create a mock server with a simple tool
  398. mcp mock tool hello_world "A simple greeting tool"
  399. # Create a mock server with multiple entity types
  400. mcp mock tool hello_world "A greeting tool" \
  401. prompt welcome "A welcome prompt" "Hello {{name}}, welcome to {{location}}!" \
  402. resource docs://readme "Documentation" "Mock MCP Server\nThis is a mock server"
  403. ```
  404. Features of the mock server:
  405. - Full initialization handshake
  406. - Tool listing with standardized schema
  407. - Tool calling with simple responses
  408. - Resource listing and reading
  409. - Prompt listing and retrieval with argument substitution
  410. - Detailed request/response logging to `~/.mcpt/logs/mock.log`
  411. #### Using Prompt Templates
  412. For prompts, any text in `{{double_braces}}` is automatically detected as an argument:
  413. ```bash
  414. # Create a prompt with name and location arguments
  415. mcp mock prompt greeting "Greeting template" "Hello {{name}}! Welcome to {{location}}."
  416. ```
  417. When a client requests the prompt, it can provide values for these arguments which will be substituted in the response.
  418. ### Proxy Mode
  419. The proxy mode allows you to register shell scripts or inline commands as MCP tools, making it easy to extend MCP functionality without writing code:
  420. ```bash
  421. # Register a shell script as an MCP tool
  422. mcp proxy tool add_operation "Adds a and b" "a:int,b:int" ./examples/add.sh
  423. # Register an inline command as an MCP tool
  424. mcp proxy tool add_operation "Adds a and b" "a:int,b:int" -e 'echo "total is $a + $b = $(($a+$b))"'
  425. # Register an inline command as an MCP tool with optional parameter
  426. mcpt proxy tool add_operation "Adds a and b with optional result msg" "a:int,b:int,[msg:string]" -e 'echo "$msg$a + $b = $(($a+$b))"'
  427. # Unregister a tool
  428. mcp proxy tool --unregister add_operation
  429. # Start the proxy server
  430. mcp proxy start
  431. ```
  432. Running `mcp tools localhost:3000` with the proxy server will show the registered tools with their parameters:
  433. ```
  434. add_operation(a:int, b:int)
  435. Adds a and b
  436. count_files(dir:str, [include:str[]])
  437. Counts files in a directory with optional filters
  438. ```
  439. This new format clearly shows what parameters each tool accepts, making it easier to understand how to use them. Arrays are denoted with `[]` suffix (e.g., `str[]`), and type names are shortened for better readability.
  440. #### How It Works
  441. 1. Register a shell script or inline command with a tool name, description, and parameter specification
  442. 2. Start the proxy server, which implements the MCP protocol
  443. 3. When a tool is called, parameters are passed as environment variables to the script/command
  444. 4. The script/command's output is returned as the tool response
  445. 5. If the script's output is a base64-encoded PNG image (prefixed with `data:image/png;base64,`), it is returned as an [ImageContent](https://modelcontextprotocol.io/specification/2025-06-18/server/prompts#image-content) object.
  446. #### Example Scripts and Commands
  447. **Adding Numbers (add.sh):**
  448. ```bash
  449. #!/bin/bash
  450. # Get values from environment variables
  451. if [ -z "$a" ] || [ -z "$b" ]; then
  452. echo "Error: Missing required parameters 'a' or 'b'"
  453. exit 1
  454. fi
  455. # Perform the addition
  456. result=$(($a + $b))
  457. echo "The sum of $a and $b is $result"
  458. ```
  459. **Generating a QR Code**
  460. This example requires a tool like `qrencode` to be installed.
  461. ```bash
  462. # Register a tool to generate a QR code
  463. mcp proxy tool qrcode "Generates a QR code" "text:string" \
  464. -e 'echo -e "data:image/png;base64,$(qrencode -t png -o - "$text" | base64 -w 0)"'
  465. ```
  466. **Inline Command Example:**
  467. ```bash
  468. # Simple addition
  469. mcp proxy tool add_op "Adds given numbers" "a:int,b:int" -e 'echo "total is $a + $b = $(($a+$b))"'
  470. # Customized greeting
  471. mcp proxy tool greet "Greets a user" "name:string,greeting:string,formal:bool" -e '
  472. if [ "$formal" = "true" ]; then
  473. title="Mr./Ms."
  474. echo "${greeting:-Hello}, ${title} ${name}. How may I assist you today?"
  475. else
  476. echo "${greeting:-Hello}, ${name}! Nice to meet you!"
  477. fi
  478. '
  479. # File operations
  480. mcp proxy tool count_lines "Counts lines in a file" "file:string" -e "wc -l < \"$file\""
  481. ```
  482. #### Configuration and Logging
  483. - Tools are registered in `~/.mcpt/proxy_config.json`
  484. - The proxy server logs all requests and responses to `~/.mcpt/logs/proxy.log`
  485. - Use `--unregister` to remove a tool from the configuration
  486. ### Guard Mode
  487. The guard mode allows you to restrict access to specific tools, prompts, and resources based on pattern matching. This is useful for security purposes when:
  488. - Restricting potentially dangerous operations (file writes, deletions, etc.)
  489. - Limiting the capabilities of AI assistants or applications
  490. - Providing read-only access to sensitive systems
  491. - Creating sandboxed environments for testing or demonstrations
  492. > **Note:** Guard mode currently only works with STDIO transport (command execution) and not HTTP transport.
  493. ```bash
  494. # Allow only file reading operations, deny file modifications
  495. mcp guard --allow 'tools:read_* --deny tools:write_*,create_*,delete_*' npx -y @modelcontextprotocol/server-filesystem ~
  496. # Permit only a single specific tool
  497. mcp guard --allow 'tools:search_files' npx -y @modelcontextprotocol/server-filesystem ~
  498. # Restrict by both tool type and prompt type
  499. mcp guard --allow 'tools:read_*,prompts:system_*' --deny tools:execute_* npx -y @modelcontextprotocol/server-filesystem ~
  500. # Using with aliases
  501. mcp guard --allow 'tools:read_*' fs # Where 'fs' is an alias for a filesystem server
  502. ```
  503. #### How It Works
  504. The guard command works by:
  505. 1. Creating a proxy that sits between the client and the MCP server
  506. 2. Intercepting and filtering all requests to `tools/list`, `prompts/list`, and `resources/list`
  507. 3. Preventing calls to tools, prompts, or resources that don't match the allowed patterns
  508. 4. Blocking requests for filtered resources, tools and prompts
  509. 6. Passing through all other requests and responses unchanged
  510. #### Pattern Matching
  511. Patterns use simple glob syntax with `*` as a wildcard:
  512. - `tools:read_*` - Matches all tools starting with "read_"
  513. - `tools:*file*` - Matches any tool with "file" in the name
  514. - `prompts:system_*` - Matches all prompts starting with "system_"
  515. For each entity type, you can specify:
  516. - `--allow 'pattern1,pattern2,...'` - Only allow entities matching these patterns
  517. - `--deny 'pattern1,pattern2,...'` - Remove entities matching these patterns
  518. If no allow patterns are specified, all entities are allowed by default (except those matching deny patterns).
  519. #### Application Integration
  520. You can use the guard command to secure MCP configurations in applications. For example, to restrict a file system server to only allow read operations, change:
  521. ```json
  522. "filesystem": {
  523. "command": "npx",
  524. "args": [
  525. "-y",
  526. "@modelcontextprotocol/server-filesystem",
  527. "/Users/fka/Desktop"
  528. ]
  529. }
  530. ```
  531. To:
  532. ```json
  533. "filesystem": {
  534. "command": "mcp",
  535. "args": [
  536. "guard", "--deny", "tools:write_*,create_*,move_*,delete_*",
  537. "npx", "-y", "@modelcontextprotocol/server-filesystem",
  538. "/Users/fka/Desktop"
  539. ]
  540. }
  541. ```
  542. This provides a read-only view of the filesystem by preventing any modification operations.
  543. You can also use aliases with the guard command in configurations:
  544. ```json
  545. "filesystem": {
  546. "command": "mcp",
  547. "args": [
  548. "guard", "--allow", "tools:read_*,list_*,search_*",
  549. "fs" // Where 'fs' is an alias for the filesystem server
  550. ]
  551. }
  552. ```
  553. This makes your configurations even more concise and easier to maintain.
  554. #### Logging
  555. - Guard operations are logged to `~/.mcpt/logs/guard.log`
  556. - The log includes all requests, responses, and filtering decisions
  557. - Use `tail -f ~/.mcpt/logs/guard.log` to monitor activity in real-time
  558. ## Examples
  559. ### Basic Usage
  560. List tools from a filesystem server:
  561. ```bash
  562. mcp tools npx -y @modelcontextprotocol/server-filesystem ~
  563. ```
  564. Call a tool with pretty JSON output:
  565. ```bash
  566. mcp call read_file --params '{"path":"README.md"}' --format pretty npx -y @modelcontextprotocol/server-filesystem ~
  567. ```
  568. Use the guard mode to filter available tools:
  569. ```bash
  570. # Only allow file search functionality
  571. mcp guard --allow tools:search_files npx -y @modelcontextprotocol/server-filesystem ~
  572. # Create a read-only environment
  573. mcp guard --deny tools:write_*,delete_*,create_*,move_* npx -y @modelcontextprotocol/server-filesystem ~
  574. ```
  575. ### Streamable HTTP Usage
  576. Create and run a local streamable HTTP server:
  577. ```bash
  578. # Create a new MCP server with SSE transport (streamable HTTP not available in scaffolding)
  579. mkdir my-sse-server && cd my-sse-server
  580. mcp new tool:example_tool --transport=sse
  581. # Install dependencies and build
  582. npm install && npm run build
  583. # Start the server (will run SSE transport)
  584. npm start
  585. ```
  586. In a separate terminal, connect to your local server:
  587. ```bash
  588. # Connect to local SSE server (adjust URL based on your server's SSE endpoint)
  589. mcp tools http://localhost:3000/sse
  590. # Call a tool on the local server
  591. mcp call example_tool --params '{"input": "test"}' http://localhost:3000/sse
  592. # Use with different output formats
  593. mcp tools --format pretty http://localhost:3000/sse
  594. ```
  595. Connect to remote streamable HTTP servers:
  596. ```bash
  597. # Connect to a remote MCP server
  598. mcp tools https://api.example.com/mcp
  599. # Use SSE transport for legacy servers (auto-detected from /sse path)
  600. mcp tools http://legacy-server.com/sse
  601. # Example with authentication headers (when supported)
  602. mcp tools https://authenticated-mcp-server.com
  603. ```
  604. ### Script Integration
  605. Using the proxy mode with a simple shell script:
  606. ```bash
  607. # 1. Create a simple shell script for addition
  608. cat > add.sh << 'EOF'
  609. #!/bin/bash
  610. # Get values from environment variables
  611. if [ -z "$a" ] || [ -z "$b" ]; then
  612. echo "Error: Missing required parameters 'a' or 'b'"
  613. exit 1
  614. fi
  615. result=$(($a + $b))
  616. echo "The sum of $a and $b is $result"
  617. EOF
  618. # 2. Make it executable
  619. chmod +x add.sh
  620. # 3. Register it as an MCP tool
  621. mcp proxy tool add_numbers "Adds two numbers" "a:int,b:int" ./add.sh
  622. # 4. In one terminal, start the proxy server
  623. mcp proxy start
  624. # 5. In another terminal, you can call it as an MCP tool
  625. mcp call add_numbers --params '{"a":5,"b":3}' --format pretty
  626. ```
  627. ### Debugging
  628. Tailing the logs to debug your proxy or mock server:
  629. ```bash
  630. # For the mock server logs
  631. tail -f ~/.mcpt/logs/mock.log
  632. # For the proxy server logs
  633. tail -f ~/.mcpt/logs/proxy.log
  634. # To watch all logs in real-time (on macOS/Linux)
  635. find ~/.mcpt/logs -name "*.log" -exec tail -f {} \;
  636. ```
  637. ## Contributing
  638. We welcome contributions! Please see our [Contributing Guidelines](CONTRIBUTING.md) for details on how to submit pull requests, report issues, and contribute to the project.
  639. ## Roadmap
  640. The following features are planned for future releases:
  641. - Authentication: Support for secure authentication mechanisms
  642. ## License
  643. This project is licensed under the MIT License.
  644. ## Thanks
  645. Thanks to [Fatih Taskiran](https://bsky.app/profile/fatih.co) for the logo design.

Ratings and comments

Sign in to rate this skill.

Sign in

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