{"id":26718555,"url":"https://github.com/f/mcptools","last_synced_at":"2025-05-16T18:05:19.297Z","repository":{"id":284491644,"uuid":"954858451","full_name":"f/mcptools","owner":"f","description":"A command-line interface for interacting with MCP (Model Context Protocol) servers using both stdio and HTTP transport.","archived":false,"fork":false,"pushed_at":"2025-05-05T20:39:26.000Z","size":18875,"stargazers_count":643,"open_issues_count":8,"forks_count":33,"subscribers_count":5,"default_branch":"master","last_synced_at":"2025-05-16T18:02:59.591Z","etag":null,"topics":["mcp","mcp-server","modelcontextprotocol"],"latest_commit_sha":null,"homepage":"","language":"Go","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/f.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","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-03-25T18:14:37.000Z","updated_at":"2025-05-16T14:09:14.000Z","dependencies_parsed_at":"2025-03-26T07:23:50.485Z","dependency_job_id":"0c8181ea-5922-4033-bf9d-f9715a795e00","html_url":"https://github.com/f/mcptools","commit_stats":null,"previous_names":["f/mcptools"],"tags_count":34,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/f%2Fmcptools","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/f%2Fmcptools/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/f%2Fmcptools/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/f%2Fmcptools/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/f","download_url":"https://codeload.github.com/f/mcptools/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":254582903,"owners_count":22095518,"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":["mcp","mcp-server","modelcontextprotocol"],"created_at":"2025-03-27T17:35:00.264Z","updated_at":"2025-05-16T18:05:19.290Z","avatar_url":"https://github.com/f.png","language":"Go","readme":"\u003cp align=\"center\"\u003e\n  \u003cimg src=\"./.github/resources/logo.png\" alt=\"MCP Tools\" height=\"150\"\u003e\n\u003c/p\u003e\n\n\u003cp align=\"center\"\u003e\n  \u003ch1 align=\"center\"\u003eSwiss Army Knife for MCP Servers\u003c/h1\u003e\n  \u003cp align=\"center\"\u003e\n    A comprehensive command-line interface for interacting with MCP (Model Context Protocol) servers.\n    \u003cbr\u003e\n    Discover, call, and manage tools, resources, and prompts from any MCP-compatible server.\n    \u003cbr\u003e\n    Supports multiple transport methods, output formats, and includes powerful mock and proxy server capabilities.\n  \u003c/p\u003e\n\u003c/p\u003e\n\n[![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/)\n\n## Table of Contents\n\n- [Overview](#overview)\n- [Difference Between the MCP Inspector and MCP Tools](https://blog.fka.dev/blog/2025-03-27-mcp-inspector-vs-mcp-tools/)\n- [Installation](#installation)\n  - [Using Homebrew](#using-homebrew)\n  - [From Source](#from-source)\n- [Getting Started](#getting-started)\n- [Features](#features)\n  - [Transport Options](#transport-options)\n  - [Output Formats](#output-formats)\n  - [Commands](#commands)\n  - [Interactive Shell](#interactive-shell)\n  - [Web Interface](#web-interface)\n  - [Project Scaffolding](#project-scaffolding)\n- [Server Aliases](#server-aliases)\n- [LLM Apps Config Management](#llm-apps-config-management)\n- [Server Modes](#server-modes)\n  - [Mock Server Mode](#mock-server-mode)\n  - [Proxy Mode](#proxy-mode)\n  - [Guard Mode](#guard-mode)\n- [Examples](#examples)\n  - [Basic Usage](#basic-usage)\n  - [Script Integration](#script-integration)\n  - [Debugging](#debugging)\n- [Contributing](#contributing)\n- [Roadmap](#roadmap)\n- [License](#license)\n\n## Overview\n\nMCP Tools provides a versatile CLI for working with Model Context Protocol (MCP) servers. It enables you to:\n\n- Discover and call tools provided by MCP servers\n- Access and utilize resources exposed by MCP servers\n- Create mock servers for testing client applications\n- Proxy MCP requests to shell scripts for easy extensibility\n- Create interactive shells for exploring and using MCP servers\n- Scaffold new MCP projects with TypeScript support\n- Format output in various styles (JSON, pretty-printed, table)\n- Guard and restrict access to specific tools and resources\n- Support all transport methods (HTTP, stdio)\n\n\u003cp align=\"center\"\u003e\n  \u003cimg src=\".github/resources/screenshot.png\" alt=\"MCP Tools Screenshot\" width=\"700\"\u003e\n\u003c/p\u003e\n\n## Installation\n\n### Using Homebrew (for macOS)\n\n```bash\nbrew tap f/mcptools\nbrew install mcp\n```\n\n\u003e ❕ 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.\n\n### From Source (for Windows and GNU/Linux)\n\n```bash\ngo install github.com/f/mcptools/cmd/mcptools@latest\n```\n\n\u003e ❕ The binary will be installed as `mcptools` when but can be aliased to `mcpt` for convenience.\n\u003e \n\u003e \u003cimg width=\"500\" alt=\"Screenshot 2025-05-05 at 22 21 29\" src=\"https://github.com/user-attachments/assets/eaba88c1-8833-4525-bb19-9ab0ec2ff27e\" /\u003e\n\u003e \n\u003e \u003csub\u003eWindows 11 Running Example\u003c/sub\u003e\n\n## Getting Started\n\nThe simplest way to start using MCP Tools is to connect to an MCP server and list available tools:\n\n```bash\n# List all available tools from a filesystem server\nmcp tools npx -y @modelcontextprotocol/server-filesystem ~\n\n# Call a specific tool\nmcp call read_file --params '{\"path\":\"README.md\"}' npx -y @modelcontextprotocol/server-filesystem ~\n\n# Open an interactive shell\nmcp shell npx -y @modelcontextprotocol/server-filesystem ~\n```\n\n## Features\n\nMCP Tools supports a wide range of features for interacting with MCP servers:\n\n```\nUsage:\n  mcp [command]\n\nAvailable Commands:\n  version       Print the version information\n  tools         List available tools on the MCP server\n  resources     List available resources on the MCP server\n  prompts       List available prompts on the MCP server\n  call          Call a tool, resource, or prompt on the MCP server\n  get-prompt    Get a prompt on the MCP server\n  read-resource Read a resource on the MCP server\n  shell         Start an interactive shell for MCP commands\n  web           Start a web interface for MCP commands\n  mock          Create a mock MCP server with tools, prompts, and resources\n  proxy         Proxy MCP tool requests to shell scripts\n  alias         Manage MCP server aliases\n  configs       Manage MCP server configurations\n  new           Create a new MCP project component\n  help          Help about any command\n  completion    Generate the autocompletion script for the specified shell\n\nFlags:\n  -f, --format string   Output format (table, json, pretty) (default \"table\")\n  -h, --help            help for mcp\n  -p, --params string   JSON string of parameters to pass to the tool (for call command) (default \"{}\")\n\nUse \"mcp [command] --help\" for more information about a command.\n```\n\n### Transport Options\n\nMCP Tools supports multiple transport methods for communicating with MCP servers:\n\n#### Stdio Transport\n\nUses 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.\n\n```bash\nmcp tools npx -y @modelcontextprotocol/server-filesystem ~\n```\n\n#### HTTP SSE Transport\n\nUses 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 MCP protocol.\n\n```bash\nmcp tools http://localhost:3001/sse\n\n# Example: Use the everything sample server\n# docker run -p 3001:3001 --rm -it tzolov/mcp-everything-server:v1\n```\n\n_Note:_ HTTP SSE currently supports only MCP protocol version 2024-11-05.\n\n### Output Formats\n\nMCP Tools supports three output formats to accommodate different needs:\n\n#### Table Format (Default)\n\n```bash\nmcp tools npx -y @modelcontextprotocol/server-filesystem ~\n```\n\nThe default format now displays tools in a colorized man-page style:\n\n```\nread_file(path:str)\n     Read the complete contents of a file from the file system.\nread_multiple_files(paths:str[])\n     Read the contents of multiple files simultaneously.\nlist_dir(path:str)\n     Lists the contents of a directory.\nwrite_file(path:str, content:str)\n     Writes content to a file.\ngrep_search(pattern:str, [excludePatterns:str[]])\n     Search files with pattern.\nedit_file(edits:{newText:str,oldText:str}[], path:str)\n     Edit a file with multiple text replacements\n```\n\nKey features of the format:\n- Function names are displayed in bold cyan\n- Required parameters are shown in green (e.g., `path:str`)\n- Optional parameters are shown in yellow brackets (e.g., `[limit:int]`)\n- Array types are indicated with `[]` suffix (e.g., `str[]`)\n- Object types show their properties in curly braces (e.g., `{prop1:type1,prop2:type2}`)\n- Nested objects are displayed recursively (e.g., `{notifications:{enabled:bool,sound:bool}}`)\n- Type names are shortened for readability (e.g., `str` instead of `string`, `int` instead of `integer`)\n- Descriptions are indented and displayed in gray\n- Parameter order is consistent, with required parameters listed first\n\n#### JSON Format (Compact)\n\n```bash\nmcp tools --format json npx -y @modelcontextprotocol/server-filesystem ~\n```\n\n#### Pretty JSON Format (Indented)\n\n```bash\nmcp tools --format pretty npx -y @modelcontextprotocol/server-filesystem ~\n```\n\n### Commands\n\nMCP Tools includes several core commands for interacting with MCP servers:\n\n#### List Available Tools\n\n```bash\nmcp tools npx -y @modelcontextprotocol/server-filesystem ~\n```\n\n#### List Available Resources\n\n```bash\nmcp resources npx -y @modelcontextprotocol/server-filesystem ~\n```\n\n#### List Available Prompts\n\n```bash\nmcp prompts npx -y @modelcontextprotocol/server-filesystem ~\n```\n\n#### Call a Tool\n\n```bash\nmcp call read_file --params '{\"path\":\"/path/to/file\"}' npx -y @modelcontextprotocol/server-filesystem ~\n```\n\n#### Call a Resource\n\n```bash\nmcp call resource:test://static/resource/1 npx -y @modelcontextprotocol/server-everything -f json | jq \".contents[0].text\"\n```\n\nor\n\n```bash\nmcp read-resource test://static/resource/1 npx -y @modelcontextprotocol/server-everything -f json | jq \".contents[0].text\"\n```\n\n#### Call a Prompt\n\n```bash\nmcp get-prompt simple_prompt npx -y @modelcontextprotocol/server-everything -f json | jq \".messages[0].content.text\"\n```\n\n#### Viewing Server Logs\n\nWhen 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:\n\n```bash\n# View server logs when listing tools\nmcp tools --server-logs npx -y @modelcontextprotocol/server-filesystem ~\n```\n\nOutput:\n```\n[\u003e] Secure MCP Filesystem Server running on stdio\n[\u003e] Allowed directories: [ '/Users/fka/' ]\nread_file(path:str)\n     Read the complete contents of a file from the file system.\nread_multiple_files(paths:str[])\n     Read the contents of multiple files simultaneously.\n... and the other tools available on this server\n```\n\nThis can be helpful for debugging or understanding what's happening on the server side when executing these commands.\n\n### Interactive Shell\n\nThe interactive shell mode allows you to run multiple MCP commands in a single session:\n\n```bash\nmcp shell npx -y @modelcontextprotocol/server-filesystem ~\n```\n\nThis opens an interactive shell with the following capabilities:\n\n```\nmcp tools shell\nconnected to: npx -y @modelcontextprotocol/server-filesystem /Users/fka\n\nmcp \u003e Type '/h' for help or '/q' to quit\nmcp \u003e tools\nread_file(path:str, [limit:int], [offset:int])\n     Reads a file from the filesystem\n\nlist_dir(path:str)\n     Lists directory contents\n\ngrep_search(pattern:str, [excludePatterns:str[]])\n     Search files with pattern\n\nedit_file(edits:{newText:str,oldText:str}[], path:str)\n     Edit a file with multiple text replacements\n\n# Direct tool calling is supported\nmcp \u003e read_file {\"path\":\"README.md\"}\n...content of README.md...\n\n# Calling a tool with complex object parameters\nmcp \u003e edit_file {\"path\":\"main.go\",\"edits\":[{\"oldText\":\"foo\",\"newText\":\"bar\"}]}\n...result of edit operation...\n\n# Get help\nmcp \u003e /h\nMCP Shell Commands:\n  tools                      List available tools\n  resources                  List available resources\n  prompts                    List available prompts\n  call \u003centity\u003e [--params '{...}']  Call a tool, resource, or prompt\n  format [json|pretty|table] Get or set output format\nSpecial Commands:\n  /h, /help                  Show this help\n  /q, /quit, exit            Exit the shell\n```\n\n### Web Interface\n\nMCP Tools provides a web interface for interacting with MCP servers through a browser-based UI:\n\n```bash\n# Start a web interface for a filesystem server on default port (41999)\nmcp web npx -y @modelcontextprotocol/server-filesystem ~\n\n# Use a custom port\nmcp web --port 8080 docker run -i --rm -e GITHUB_PERSONAL_ACCESS_TOKEN ghcr.io/github/github-mcp-server\n\n# Use SSE\nmcp web https://ne.tools\n```\n\nThe web interface includes:\n\n- A sidebar listing all available tools, resources, and prompts\n- Form-based and JSON-based parameter editing\n- Formatted and raw JSON response views\n- Interactive parameter forms automatically generated from tool schemas\n- Support for complex parameter types (arrays, objects, nested structures)\n- Direct API access for tool calling\n\nOnce started, you can access the interface by opening `http://localhost:41999` (or your custom port) in a browser.\n\n\u003cp align=\"center\"\u003e\n  \u003cimg src=\".github/resources/web-interface.png\" alt=\"MCP Web Interface\" width=\"700\"\u003e\n\u003c/p\u003e\n\n### Project Scaffolding\n\nMCP Tools provides a scaffolding feature to quickly create new MCP servers with TypeScript:\n\n```bash\nmkdir my-mcp-server\ncd my-mcp-server\n\n# Create a project with specific components\nmcp new tool:calculate resource:file prompt:greet\n\n# Create a project with a specific SDK (currently only TypeScript/ts supported)\nmcp new tool:calculate --sdk=ts\n\n# Create a project with a specific transport type\nmcp new tool:calculate --transport=stdio\nmcp new tool:calculate --transport=sse\n```\n\nThe scaffolding creates a complete project structure with:\n\n- Server setup with chosen transport (stdio or SSE)\n- TypeScript configuration with modern ES modules\n- Component implementations with proper MCP interfaces\n- Automatic wiring of imports and initialization\n\nAfter scaffolding, you can build and run your MCP server:\n\n```bash\n# Install dependencies\nnpm install\n\n# Build the TypeScript code\nnpm run build\n\n# Test the server with MCP Tools\nmcp tools node build/index.js\n```\n\nProject templates are stored in either:\n- Local `./templates/` directory\n- User's home directory: `~/.mcpt/templates/`\n- Homebrew installation path (`/opt/homebrew/Cellar/mcp/v#.#.#/templates`)\n\nWhen installing via Homebrew, templates are automatically installed to your home directory. But if you use source install, you need to run `make install-templates`.\n\n## Server Aliases\n\nMCP Tools allows you to save and reuse server commands with friendly aliases:\n\n```bash\n# Add a new server alias\nmcp alias add myfs npx -y @modelcontextprotocol/server-filesystem ~/\n\n# List all registered server aliases\nmcp alias list\n\n# Remove a server alias\nmcp alias remove myfs\n\n# Use an alias with any MCP command\nmcp tools myfs\nmcp call read_file --params '{\"path\":\"README.md\"}' myfs\n```\n\nServer 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.\n\n## LLM Apps Config Management\n\nMCP Tools provides a powerful configuration management system that helps you work with MCP server configurations across multiple applications:\n\n\u003e 🚧 This works only on macOS for now.\n\n```bash\n# Scan for MCP server configurations across all supported applications\nmcp configs scan\n\n# List all configurations (alias for configs view --all)\nmcp configs ls\n\n# View specific configuration by alias\nmcp configs view vscode\n\n# Add or update a server in a configuration\nmcp configs set vscode my-server npm run mcp-server\nmcp configs set cursor my-api https://api.example.com/mcp --headers \"Authorization=Bearer token\"\n\n# Add to multiple configurations at once\nmcp configs set vscode,cursor,claude-desktop my-server npm run mcp-server\n\n# Remove a server from a configuration\nmcp configs remove vscode my-server\n\n# Create an alias for a custom config file\nmcp configs alias myapp ~/myapp/config.json\n\n# Synchronize and merge configurations from multiple sources\nmcp configs sync vscode cursor --output vscode --default interactive\n\n# Convert a command line to MCP server JSON configuration format\nmcp configs as-json mcp proxy start\n# Output: {\"command\":\"mcp\",\"args\":[\"proxy\",\"start\"]}\n\n# Convert a URL to MCP server JSON configuration format\nmcp configs as-json https://api.example.com/mcp --headers \"Authorization=Bearer token\"\n# Output: {\"url\":\"https://api.example.com/mcp\",\"headers\":{\"Authorization\":\"Bearer token\"}}\n```\n\nConfigurations are managed through a central registry in `$HOME/.mcpt/configs.json` with predefined aliases for:\n- VS Code and VS Code Insiders\n- Windsurf\n- Cursor\n- Claude Desktop and Claude Code\n\nThe system automatically displays server configurations in a colorized format grouped by source, showing command-line or URL information, headers, and environment variables.\n\n`mcp configs scan` command looks for MCP server configurations in:\n- Visual Studio Code\n- Visual Studio Code Insiders\n- Windsurf\n- Cursor\n- Claude Desktop\n\nExample Output:\n```\nVS Code Insiders\n  GitHub (stdio):\n    docker run -i --rm -e GITHUB_PERSONAL_ACCESS_TOKEN ghcr.io/github/github-mcp-server\n\nClaude Desktop\n  Proxy (stdio):\n    mcp proxy start\n\n  My Files (stdio):\n    npx -y @modelcontextprotocol/server-filesystem ~/\n```\n\n### Bonus\n\nAdd official GitHub MCP Server to Windsurf, Cursor and VS Code at once:\n\n```bash\nmcp configs set windsurf,cursor,vscode GitHub \\\n  --env \"GITHUB_PERSONAL_ACCESS_TOKEN=github_pat_xxx\" \\\n  docker run -i --rm -e GITHUB_PERSONAL_ACCESS_TOKEN ghcr.io/github/github-mcp-server\n```\n\n\u003cp align=\"center\"\u003e\n  \u003cimg src=\".github/resources/configs.png\" alt=\"MCP Configs Screenshot\" width=\"700\"\u003e\n\u003c/p\u003e\n\n## Server Modes\n\nMCP Tools can operate as both a client and a server, with two server modes available:\n\n### Mock Server Mode\n\nThe mock server mode creates a simulated MCP server for testing clients without implementing a full server:\n\n```bash\n# Create a mock server with a simple tool\nmcp mock tool hello_world \"A simple greeting tool\"\n\n# Create a mock server with multiple entity types\nmcp mock tool hello_world \"A greeting tool\" \\\n       prompt welcome \"A welcome prompt\" \"Hello {{name}}, welcome to {{location}}!\" \\\n       resource docs://readme \"Documentation\" \"Mock MCP Server\\nThis is a mock server\"\n```\n\nFeatures of the mock server:\n\n- Full initialization handshake\n- Tool listing with standardized schema\n- Tool calling with simple responses\n- Resource listing and reading\n- Prompt listing and retrieval with argument substitution\n- Detailed request/response logging to `~/.mcpt/logs/mock.log`\n\n#### Using Prompt Templates\n\nFor prompts, any text in `{{double_braces}}` is automatically detected as an argument:\n\n```bash\n# Create a prompt with name and location arguments\nmcp mock prompt greeting \"Greeting template\" \"Hello {{name}}! Welcome to {{location}}.\"\n```\n\nWhen a client requests the prompt, it can provide values for these arguments which will be substituted in the response.\n\n### Proxy Mode\n\nThe proxy mode allows you to register shell scripts or inline commands as MCP tools, making it easy to extend MCP functionality without writing code:\n\n```bash\n# Register a shell script as an MCP tool\nmcp proxy tool add_operation \"Adds a and b\" \"a:int,b:int\" ./examples/add.sh\n\n# Register an inline command as an MCP tool\nmcp proxy tool add_operation \"Adds a and b\" \"a:int,b:int\" -e 'echo \"total is $a + $b = $(($a+$b))\"'\n\n# Unregister a tool\nmcp proxy tool --unregister add_operation\n\n# Start the proxy server\nmcp proxy start\n```\n\nRunning `mcp tools localhost:3000` with the proxy server will show the registered tools with their parameters:\n\n```\nadd_operation(a:int, b:int)\n     Adds a and b\n\ncount_files(dir:str, [include:str[]])\n     Counts files in a directory with optional filters\n```\n\nThis 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.\n\n#### How It Works\n\n1. Register a shell script or inline command with a tool name, description, and parameter specification\n2. Start the proxy server, which implements the MCP protocol\n3. When a tool is called, parameters are passed as environment variables to the script/command\n4. The script/command's output is returned as the tool response\n\n#### Example Scripts and Commands\n\n**Adding Numbers (add.sh):**\n\n```bash\n#!/bin/bash\n# Get values from environment variables\nif [ -z \"$a\" ] || [ -z \"$b\" ]; then\n  echo \"Error: Missing required parameters 'a' or 'b'\"\n  exit 1\nfi\n\n# Perform the addition\nresult=$(($a + $b))\necho \"The sum of $a and $b is $result\"\n```\n\n**Inline Command Example:**\n\n```bash\n# Simple addition\nmcp proxy tool add_op \"Adds given numbers\" \"a:int,b:int\" -e 'echo \"total is $a + $b = $(($a+$b))\"'\n\n# Customized greeting\nmcp proxy tool greet \"Greets a user\" \"name:string,greeting:string,formal:bool\" -e '\nif [ \"$formal\" = \"true\" ]; then\n  title=\"Mr./Ms.\"\n  echo \"${greeting:-Hello}, ${title} ${name}. How may I assist you today?\"\nelse\n  echo \"${greeting:-Hello}, ${name}! Nice to meet you!\"\nfi\n'\n\n# File operations\nmcp proxy tool count_lines \"Counts lines in a file\" \"file:string\" -e \"wc -l \u003c \\\"$file\\\"\"\n```\n\n#### Configuration and Logging\n\n- Tools are registered in `~/.mcpt/proxy_config.json`\n- The proxy server logs all requests and responses to `~/.mcpt/logs/proxy.log`\n- Use `--unregister` to remove a tool from the configuration\n\n### Guard Mode\n\nThe guard mode allows you to restrict access to specific tools, prompts, and resources based on pattern matching. This is useful for security purposes when:\n\n- Restricting potentially dangerous operations (file writes, deletions, etc.)\n- Limiting the capabilities of AI assistants or applications\n- Providing read-only access to sensitive systems\n- Creating sandboxed environments for testing or demonstrations\n\n\u003e **Note:** Guard mode currently only works with STDIO transport (command execution) and not HTTP transport.\n\n```bash\n# Allow only file reading operations, deny file modifications\nmcp guard --allow 'tools:read_* --deny tools:write_*,create_*,delete_*' npx -y @modelcontextprotocol/server-filesystem ~\n\n# Permit only a single specific tool\nmcp guard --allow 'tools:search_files' npx -y @modelcontextprotocol/server-filesystem ~\n\n# Restrict by both tool type and prompt type\nmcp guard --allow 'tools:read_*,prompts:system_*' --deny tools:execute_* npx -y @modelcontextprotocol/server-filesystem ~\n\n# Using with aliases\nmcp guard --allow 'tools:read_*' fs  # Where 'fs' is an alias for a filesystem server\n```\n\n#### How It Works\n\nThe guard command works by:\n1. Creating a proxy that sits between the client and the MCP server\n2. Intercepting and filtering all requests to `tools/list`, `prompts/list`, and `resources/list`\n3. Preventing calls to tools, prompts, or resources that don't match the allowed patterns\n4. Blocking requests for filtered resources, tools and prompts\n6. Passing through all other requests and responses unchanged\n\n#### Pattern Matching\n\nPatterns use simple glob syntax with `*` as a wildcard:\n\n- `tools:read_*` - Matches all tools starting with \"read_\"\n- `tools:*file*` - Matches any tool with \"file\" in the name\n- `prompts:system_*` - Matches all prompts starting with \"system_\"\n\nFor each entity type, you can specify:\n- `--allow 'pattern1,pattern2,...'` - Only allow entities matching these patterns\n- `--deny 'pattern1,pattern2,...'` - Remove entities matching these patterns\n\nIf no allow patterns are specified, all entities are allowed by default (except those matching deny patterns).\n\n#### Application Integration\n\nYou 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:\n\n```json\n\"filesystem\": {\n  \"command\": \"npx\",\n  \"args\": [\n    \"-y\",\n    \"@modelcontextprotocol/server-filesystem\",\n    \"/Users/fka/Desktop\"\n  ]\n}\n```\n\nTo:\n\n```json\n\"filesystem\": {\n  \"command\": \"mcp\",\n  \"args\": [\n    \"guard\", \"--deny\", \"tools:write_*,create_*,move_*,delete_*\",\n    \"npx\", \"-y\", \"@modelcontextprotocol/server-filesystem\",\n    \"/Users/fka/Desktop\"\n  ]\n}\n```\n\nThis provides a read-only view of the filesystem by preventing any modification operations.\n\nYou can also use aliases with the guard command in configurations:\n\n```json\n\"filesystem\": {\n  \"command\": \"mcp\",\n  \"args\": [\n    \"guard\", \"--allow\", \"tools:read_*,list_*,search_*\",\n    \"fs\"  // Where 'fs' is an alias for the filesystem server\n  ]\n}\n```\n\nThis makes your configurations even more concise and easier to maintain.\n\n#### Logging\n\n- Guard operations are logged to `~/.mcpt/logs/guard.log`\n- The log includes all requests, responses, and filtering decisions\n- Use `tail -f ~/.mcpt/logs/guard.log` to monitor activity in real-time\n\n## Examples\n\n### Basic Usage\n\nList tools from a filesystem server:\n\n```bash\nmcp tools npx -y @modelcontextprotocol/server-filesystem ~\n```\n\nCall a tool with pretty JSON output:\n\n```bash\nmcp call read_file --params '{\"path\":\"README.md\"}' --format pretty npx -y @modelcontextprotocol/server-filesystem ~\n```\n\nUse the guard mode to filter available tools:\n\n```bash\n# Only allow file search functionality\nmcp guard --allow tools:search_files npx -y @modelcontextprotocol/server-filesystem ~\n\n# Create a read-only environment\nmcp guard --deny tools:write_*,delete_*,create_*,move_* npx -y @modelcontextprotocol/server-filesystem ~\n```\n\n### Script Integration\n\nUsing the proxy mode with a simple shell script:\n\n```bash\n# 1. Create a simple shell script for addition\ncat \u003e add.sh \u003c\u003c 'EOF'\n#!/bin/bash\n# Get values from environment variables\nif [ -z \"$a\" ] || [ -z \"$b\" ]; then\n  echo \"Error: Missing required parameters 'a' or 'b'\"\n  exit 1\nfi\nresult=$(($a + $b))\necho \"The sum of $a and $b is $result\"\nEOF\n\n# 2. Make it executable\nchmod +x add.sh\n\n# 3. Register it as an MCP tool\nmcp proxy tool add_numbers \"Adds two numbers\" \"a:int,b:int\" ./add.sh\n\n# 4. In one terminal, start the proxy server\nmcp proxy start\n\n# 5. In another terminal, you can call it as an MCP tool\nmcp call add_numbers --params '{\"a\":5,\"b\":3}' --format pretty\n```\n\n### Debugging\n\nTailing the logs to debug your proxy or mock server:\n\n```bash\n# For the mock server logs\ntail -f ~/.mcpt/logs/mock.log\n\n# For the proxy server logs\ntail -f ~/.mcpt/logs/proxy.log\n\n# To watch all logs in real-time (on macOS/Linux)\nfind ~/.mcpt/logs -name \"*.log\" -exec tail -f {} \\;\n```\n\n## Contributing\n\nWe welcome contributions! Please see our [Contributing Guidelines](CONTRIBUTING.md) for details on how to submit pull requests, report issues, and contribute to the project.\n\n## Roadmap\n\nThe following features are planned for future releases:\n\n- Authentication: Support for secure authentication mechanisms\n\n## License\n\nThis project is licensed under the MIT License.\n\n## Thanks\n\nThanks to [Fatih Taskiran](https://bsky.app/profile/fatih.co) for the logo design.\n","funding_links":[],"categories":["Go","📚 Projects (1974 total)","⚙️ DevOps","MCP Clients","Utilities","Table of Contents","MCP Servers \u0026 Protocol"],"sub_categories":["MCP Servers","CLI Tools","Development Tools","Command Line"],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ff%2Fmcptools","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ff%2Fmcptools","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ff%2Fmcptools/lists"}