📌Overview

Purpose: MCP Tools provides a command-line interface for interacting with Model Context Protocol (MCP) servers via standard input/output.

Overview: The framework facilitates user interaction with MCP servers, enabling discovery and invocation of tools, resource management, and integration with MCP-compatible services.

Key Features:

Interactive Shell: Offers an interactive shell mode where users can execute multiple MCP commands seamlessly, enhancing usability and efficiency in command execution.
Transport Options: Currently supports STDIO transport for communication with MCP servers using JSON-RPC 2.0, making it suitable for command-line applications that implement MCP.
Flexible Output Formats: Provides output in three formats—table (default), JSON, and pretty JSON—allowing users to choose the representation that best fits their needs.

Swiss Army Knife for MCP Servers

A comprehensive command-line interface for interacting with MCP (Model Context Protocol) servers.
Discover, call, and manage tools, resources, and prompts from any MCP-compatible server.
Supports multiple transport methods, output formats, and includes powerful mock and proxy server capabilities.

Overview
Difference Between the MCP Inspector and MCP Tools
Installation
- Using Homebrew
- From Source
Getting Started
Features
- Transport Options
- Output Formats
- Commands
- Interactive Shell
- Web Interface
- Project Scaffolding
Server Aliases
LLM Apps Config Management
Server Modes
- Mock Server Mode
- Proxy Mode
- Guard Mode
Examples
- Basic Usage
- Script Integration
- Debugging
Contributing
Roadmap
License

Overview

MCP Tools provides a versatile CLI for working with Model Context Protocol (MCP) servers. It enables you to:

Discover and call tools provided by MCP servers
Access and utilize resources exposed by MCP servers
Create mock servers for testing client applications
Proxy MCP requests to shell scripts for easy extensibility
Create interactive shells for exploring and using MCP servers
Scaffold new MCP projects with TypeScript support
Format output in various styles (JSON, pretty-printed, table)
Guard and restrict access to specific tools and resources
Support all transport methods (HTTP, stdio)

Installation

Using Homebrew

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.

From Source

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

The binary will be installed as mcptools but can be aliased to mcpt for convenience.

Getting Started

Connect to an MCP server and list available tools:

# List all available tools from a filesystem server
mcp tools npx -y @modelcontextprotocol/server-filesystem ~

# Call a specific tool
mcp call read_file --params '{"path":"README.md"}' npx -y @modelcontextprotocol/server-filesystem ~

# Open an interactive shell
mcp shell npx -y @modelcontextprotocol/server-filesystem ~

Features

Usage:
  mcp [command]

Available Commands:
  version       Print the version information
  tools         List available tools on the MCP server
  resources     List available resources on the MCP server
  prompts       List available prompts on the MCP server
  call          Call a tool, resource, or prompt on the MCP server
  get-prompt    Get a prompt on the MCP server
  read-resource Read a resource on the MCP server
  shell         Start an interactive shell for MCP commands
  web           Start a web interface for MCP commands
  mock          Create a mock MCP server with tools, prompts, and resources
  proxy         Proxy MCP tool requests to shell scripts
  alias         Manage MCP server aliases
  configs       Manage MCP server configurations
  new           Create a new MCP project component
  help          Help about any command
  completion    Generate the autocompletion script for the specified shell

Flags:
  -f, --format string   Output format (table, json, pretty) (default "table")
  -h, --help            help for mcp
  -p, --params string   JSON string of parameters to pass to the tool (for call command) (default "{}")

Use "mcp [command] --help" for more information about a command.

Transport Options

MCP Tools supports multiple transport methods for communicating with MCP servers:

Stdio Transport

Uses stdin/stdout to communicate via JSON-RPC 2.0. Useful for command-line tools implementing the MCP protocol.

mcp tools npx -y @modelcontextprotocol/server-filesystem ~

HTTP SSE Transport

Uses HTTP and Server-Sent Events (SSE) to communicate via JSON-RPC 2.0. Useful for connecting to remote servers.

mcp tools http://127.0.0.1:3001

# Example: Use the everything sample server
# docker run -p 3001:3001 --rm -it tzolov/mcp-everything-server:v1

Note: HTTP SSE currently supports only MCP protocol version 2024-11-05.

Output Formats

Supports three output formats:

Table Format (Default)

Displays tools in a colorized man-page style:

read_file(path:str)
     Read the complete contents of a file from the file system.
read_multiple_files(paths:str[])
     Read the contents of multiple files simultaneously.
list_dir(path:str)
     Lists the contents of a directory.
write_file(path:str, content:str)
     Writes content to a file.
grep_search(pattern:str, [excludePatterns:str[]])
     Search files with pattern.
edit_file(edits:{newText:str,oldText:str}[], path:str)
     Edit a file with multiple text replacements

Key formatting features:

Function names in bold cyan
Required parameters in green
Optional parameters in yellow brackets
Array types with [] suffix
Object types in curly braces
Nested objects displayed recursively
Shortened type names (str instead of string, int instead of integer)
Descriptions indented in gray
Consistent parameter order: required first

JSON Format (Compact)

mcp tools --format json npx -y @modelcontextprotocol/server-filesystem ~

Pretty JSON Format (Indented)

mcp tools --format pretty npx -y @modelcontextprotocol/server-filesystem ~

Commands

Core commands:

List Available Tools

mcp tools npx -y @modelcontextprotocol/server-filesystem ~

List Available Resources

mcp resources npx -y @modelcontextprotocol/server-filesystem ~

List Available Prompts

mcp prompts npx -y @modelcontextprotocol/server-filesystem ~

Call a Tool

mcp call read_file --params '{"path":"/path/to/file"}' npx -y @modelcontextprotocol/server-filesystem ~

Call a Resource

mcp call resource:test://static/resource/1 npx -y @modelcontextprotocol/server-everything -f json | jq ".contents[0].text"

mcp read-resource test://static/resource/1 npx -y @modelcontextprotocol/server-everything -f json | jq ".contents[0].text"

Call a Prompt

mcp get-prompt simple_prompt npx -y @modelcontextprotocol/server-everything -f json | jq ".messages[0].content.text"

Viewing Server Logs

Add --server-logs flag to see server logs related to your request:

mcp tools --server-logs npx -y @modelcontextprotocol/server-filesystem ~

Output example:

[>] Secure MCP Filesystem Server running on stdio
[>] Allowed directories: [ '/Users/fka/' ]
read_file(path:str)
     Read the complete contents of a file from the file system.
...

Helpful for debugging server-side activity.

Interactive Shell

Allows running multiple MCP commands in a single session:

mcp shell npx -y @modelcontextprotocol/server-filesystem ~

Capabilities:

mcp tools shell
connected to: npx -y @modelcontextprotocol/server-filesystem /Users/fka

mcp > Type '/h' for help or '/q' to quit
mcp > tools
read_file(path:str, [limit:int], [offset:int])
     Reads a file from the filesystem

list_dir(path:str)
     Lists directory contents

grep_search(pattern:str, [excludePatterns:str[]])
     Search files with pattern

edit_file(edits:{newText:str,oldText:str}[], path:str)
     Edit a file with multiple text replacements

# Direct tool calling is supported
mcp > read_file {"path":"README.md"}
...content of README.md...

# Calling a tool with object parameters
mcp > edit_file {"path":"main.go","edits":[{"oldText":"foo","newText":"bar"}]}
...result...

# Help
mcp > /h
MCP Shell Commands:
  tools                      List available tools
  resources                  List available resources
  prompts                    List available prompts
  call <entity> [--params '{...}']  Call a tool, resource, or prompt
  format [json|pretty|table] Get or set output format
Special Commands:
  /h, /help                  Show this help
  /q, /quit, exit            Exit the shell

Web Interface

Browser-based UI for interacting with MCP servers:

# Start web interface for a filesystem server (default port 41999)
mcp web npx -y @modelcontextprotocol/server-filesystem ~

# Use a custom port
mcp web --port 8080 docker run -i --rm -e GITHUB_PERSONAL_ACCESS_TOKEN ghcr.io/github/github-mcp-server

# Use SSE transport
mcp web https://ne.tools

Features:

Sidebar listing tools, resources, prompts
Form-based and JSON parameter editing
Formatted and raw JSON responses
Auto-generated interactive parameter forms
Support for complex types (arrays, objects)
Direct API access to tools

Access interface at http://localhost:41999 or your custom port.

Project Scaffolding

Quickly create new MCP servers with TypeScript:

mkdir my-mcp-server
cd my-mcp-server

# Create project components
mcp new tool:calculate resource:file prompt:greet

# Specify SDK (currently only TypeScript/ts supported)
mcp new tool:calculate --sdk=ts

# Specify transport type
mcp new tool:calculate --transport=stdio
mcp new tool:calculate --transport=sse

Scaffolding creates:

Server setup (stdio or SSE transport)
TypeScript configuration (ES modules)
Component implementations with MCP interfaces
Automatic imports and initialization

Build and run:

npm install
npm run build
mcp tools node build/index.js

Templates are stored in either local ./templates/, user home ~/.mcpt/templates/, or Homebrew path. For source installs, run make install-templates to install.

Server Aliases

Save and reuse server commands with friendly names:

mcp alias add myfs npx -y @modelcontextprotocol/server-filesystem ~/
mcp alias list
mcp alias remove myfs

# Use alias with MCP commands
mcp tools myfs
mcp call read_file --params '{"path":"README.md"}' myfs

Aliases are stored in $HOME/.mcpt/aliases.json for convenience.

LLM Apps Config Management

Manage MCP server configurations across multiple applications (macOS only):

mcp configs scan            # Scan for MCP server configs
mcp configs ls              # List all configurations
mcp configs view vscode     # View config by alias

# Add or update server in config
mcp configs set vscode my-server npm run mcp-server
mcp configs set cursor my-api https://api.example.com/mcp --headers "Authorization=Bearer token"

# Add to multiple configs
mcp configs set vscode,cursor,claude-desktop my-server npm run mcp-server

# Remove server from config
mcp configs remove vscode my-server

# Create alias for custom config file
mcp configs alias myapp ~/myapp/config.json

# Synchronize and merge multiple configs
mcp configs sync vscode cursor --output vscode --default interactive

# Convert CLI to MCP JSON config
mcp configs as-json mcp proxy start
# Converts to JSON including command and args

# Convert URL to MCP JSON config
mcp configs as-json https://api.example.com/mcp --headers "Authorization=Bearer token"

Configurations are stored centrally in $HOME/.mcpt/configs.json with predefined aliases for:

VS Code & Insiders
Windsurf
Cursor
Claude Desktop and Claude Code

Example output of mcp configs scan:

VS Code Insiders
  GitHub (stdio):
    docker run -i --rm -e GITHUB_PERSONAL_ACCESS_TOKEN ghcr.io/github/github-mcp-server

Claude Desktop
  Proxy (stdio):
    mcp proxy start

  My Files (stdio):
    npx -y @modelcontextprotocol/server-filesystem ~/

Bonus

Add official GitHub MCP Server to Windsurf, Cursor, and VS Code simultaneously:

mcp configs set windsurf,cursor,vscode GitHub \
  --env "GITHUB_PERSONAL_ACCESS_TOKEN=github_pat_xxx" \
  docker run -i --rm -e GITHUB_PERSONAL_ACCESS_TOKEN ghcr.io/github/github-mcp-server

Server Modes

MCP Tools can act as client and server with the following modes:

Mock Server Mode

Simulated MCP server for testing clients without full implementation:

# Create mock server with a simple tool
mcp mock tool hello_world "A simple greeting tool"

# Create mock server with multiple entities
mcp mock tool hello_world "A greeting tool" \
       prompt welcome "A welcome prompt" "Hello {{name}}, welcome to {{location}}!" \
       resource docs://readme "Documentation" "Mock MCP Server\nThis is a mock server"

Features:

Full handshake initialization
Tool listing with standardized schema
Tool calls with simple responses
Resource listing and reading
Prompt listing and templated retrieval (with argument substitution)
Detailed logs at ~/.mcpt/logs/mock.log

Prompt Templates

Text in {{double_braces}} is treated as argument placeholders:

mcp mock prompt greeting "Greeting template" "Hello {{name}}! Welcome to {{location}}."

Client provides values that replace placeholders in responses.

Proxy Mode

# Register a shell script as a tool
mcp proxy tool add_operation "Adds a and b" "a:int,b:int" ./examples/add.sh

# Register an inline command as a tool
mcp proxy tool add_operation "Adds a and b" "a:int,b:int" -e 'echo "total is $a + $b = $(($a+$b))"'

# Unregister a tool
mcp proxy tool --unregister add_operation

# Start the proxy server
mcp proxy start

Calling mcp tools localhost:3000 will list registered tools and parameters:

add_operation(a:int, b:int)
     Adds a and b

count_files(dir:str, [include:str[]])
     Counts files in a directory with optional filters

Parameters marked with types and optional arrays are easy to understand.

How It Works

Register tool with name, description, parameters, and script/command.
Start the proxy server implementing MCP protocol.
Tool parameters are passed as environment variables to the script.
Script output is returned as tool response.

Example Script (add.sh)

#!/bin/bash
if [ -z "$a" ] || [ -z "$b" ]; then
  echo "Error: Missing required parameters 'a' or 'b'"
  exit 1
fi
result=$(($a + $b))
echo "The sum of $a and $b is $result"

Guard Mode

Restrict access to specific tools, prompts, and resources by pattern matching. Useful for:

Restricting dangerous operations
Limiting AI assistants capabilities
Providing read-only access
Sandboxing for demos or testing

Guard mode works only over STDIO transport.

Examples:

# Allow only file reading, deny modifications
mcp guard --allow 'tools:read_*' --deny 'tools:write_*,create_*,delete_*' npx -y @modelcontextprotocol/server-filesystem ~

# Permit only a specific tool
mcp guard --allow 'tools:search_files' npx -y @modelcontextprotocol/server-filesystem ~

# Restrict tools and prompts
mcp guard --allow 'tools:read_*,prompts:system_*' --deny 'tools:execute_*' npx -y @modelcontextprotocol/server-filesystem ~

# Using an alias
mcp guard --allow 'tools:read_*' fs

How It Works

Acts as a proxy between client and MCP server
Filters lists for tools, prompts, resources by patterns
Blocks calls to unauthorized entities
Passes other requests/responses unchanged

Pattern Matching

Using glob syntax (* wildcard):

tools:read_* — tools starting with "read_"
tools:*file* — tools containing "file"
prompts:system_* — prompts starting with "system_"

Allow and deny patterns define accessible entities.

Application Integration

Restrict file system server in config to read-only by wrapping with guard:

"filesystem": {
  "command": "mcp",
  "args": [
    "guard", "--deny", "tools:write_*,create_*,move_*,delete_*",
    "npx", "-y", "@modelcontextprotocol/server-filesystem",
    "/Users/fka/Desktop"
  ]
}

Or use aliases for simplicity:

"filesystem": {
  "command": "mcp",
  "args": [
    "guard", "--allow", "tools:read_*,list_*,search_*",
    "fs"
  ]
}

Logging

Guard operations are logged at ~/.mcpt/logs/guard.log. Use

tail -f ~/.mcpt/logs/guard.log

to monitor activity.

Examples

Basic Usage

List tools from filesystem server:

mcp tools npx -y @modelcontextprotocol/server-filesystem ~

Call a tool with pretty JSON output:

mcp call read_file --params '{"path":"README.md"}' --format pretty npx -y @modelcontextprotocol/server-filesystem ~

Use guard mode to filter tools:

mcp guard --allow tools:search_files npx -y @modelcontextprotocol/server-filesystem ~

mcp guard --deny tools:write_*,delete_*,create_*,move_* npx -y @modelcontextprotocol/server-filesystem ~

Script Integration

Use proxy mode with shell script addition:

# Create add.sh
cat > add.sh << 'EOF'
#!/bin/bash
if [ -z "$a" ] || [ -z "$b" ]; then
  echo "Error: Missing required parameters 'a' or 'b'"
  exit 1
fi
result=$(($a + $b))
echo "The sum of $a and $b is $result"
EOF

chmod +x add.sh

# Register as MCP tool
mcp proxy tool add_numbers "Adds two numbers" "a:int,b:int" ./add.sh

# Start proxy server in one terminal
mcp proxy start

# Call the tool in another terminal
mcp call add_numbers --params '{"a":5,"b":3}' --format pretty

Debugging

Tail logs for debugging:

tail -f ~/.mcpt/logs/mock.log       # Mock server logs
tail -f ~/.mcpt/logs/proxy.log      # Proxy server logs

# Watch all logs in ~/.mcpt/logs
find ~/.mcpt/logs -name "*.log" -exec tail -f {} \;

Contributing

We welcome contributions! See Contributing Guidelines for details on pull requests, issues, and contributions.

Roadmap

Planned features:

Authentication support for secure mechanisms

License

This project is licensed under the MIT License.

Thanks

Thanks to Fatih Taskiran for the logo design.

mcptools

📌Overview

Swiss Army Knife for MCP Servers

Table of Contents

Overview

Installation

Using Homebrew

From Source

Getting Started

Features

Transport Options

Stdio Transport

HTTP SSE Transport

Output Formats

Table Format (Default)

JSON Format (Compact)

Pretty JSON Format (Indented)

Commands

List Available Tools

List Available Resources

List Available Prompts

Call a Tool

Call a Resource

Call a Prompt

Viewing Server Logs

Interactive Shell

Web Interface

Project Scaffolding

Server Aliases

LLM Apps Config Management

Bonus

Server Modes

Mock Server Mode

Prompt Templates

Proxy Mode

How It Works

Example Script (add.sh)

Guard Mode

How It Works

Pattern Matching

Application Integration

Logging

Examples

Basic Usage

Script Integration

Debugging

Contributing

Roadmap

License

Thanks