brew tap f/mcptools
brew install mcp

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

# 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 ~

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.

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

mcp tools http://localhost:3001/sse

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

# Default transport for HTTP URLs
mcp tools http://localhost:3000

# Streamable HTTP transport (auto-detected from URL)
mcp tools http://localhost:3000

# Examples with remote servers
mcp tools https://api.example.com/mcp
mcp tools https://ne.tools

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

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

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

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

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

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

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

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

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"

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

# View server logs when listing tools
mcp tools --server-logs npx -y @modelcontextprotocol/server-filesystem ~

[>] 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.
read_multiple_files(paths:str[])
     Read the contents of multiple files simultaneously.
... and the other tools available on this server

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

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 complex object parameters
mcp > edit_file {"path":"main.go","edits":[{"oldText":"foo","newText":"bar"}]}
...result of edit operation...

# Get help
mcp > /h
MCP Shell Commands:
  tools                      List available tools
  resources                  List available resources
  prompts                    List available prompts
  call  [--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

# Start a web interface for a filesystem server on 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
mcp web https://ne.tools

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

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

# Create a project with a specific SDK (currently only TypeScript/ts supported)
mcp new tool:calculate --sdk=ts

# Create a project with a specific transport type
mcp new tool:calculate --transport=stdio
mcp new tool:calculate --transport=sse

# Install dependencies
npm install

# Build the TypeScript code
npm run build

# Test the server with MCP Tools
mcp tools node build/index.js

# Add a new server alias
mcp alias add myfs npx -y @modelcontextprotocol/server-filesystem ~/

# List all registered server aliases
mcp alias list

# Remove a server alias
mcp alias remove myfs

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

# Scan for MCP server configurations across all supported applications
mcp configs scan

# List all configurations (alias for configs view --all)
mcp configs ls

# View specific configuration by alias
mcp configs view vscode

# Add or update a server in a configuration
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 configurations at once
mcp configs set vscode,cursor,claude-desktop my-server npm run mcp-server

# Remove a server from a configuration
mcp configs remove vscode my-server

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

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

# Convert a command line to MCP server JSON configuration format
mcp configs as-json mcp proxy start
# Output: {"command":"mcp","args":["proxy","start"]}

# Convert a URL to MCP server JSON configuration format
mcp configs as-json https://api.example.com/mcp --headers "Authorization=Bearer token"
# Output: {"url":"https://api.example.com/mcp","headers":{"Authorization":"Bearer token"}}

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 ~/

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

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

# Create a mock server with multiple entity types
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"

# Create a prompt with name and location arguments
mcp mock prompt greeting "Greeting template" "Hello {{name}}! Welcome to {{location}}."

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

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

# Register an inline command as an MCP tool with optional parameter
 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))"'

# Unregister a tool
mcp proxy tool --unregister add_operation

# Start the proxy server
mcp proxy start

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

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

#!/bin/bash
# Get values from environment variables
if [ -z "$a" ] || [ -z "$b" ]; then
  echo "Error: Missing required parameters 'a' or 'b'"
  exit 1
fi

# Perform the addition
result=$(($a + $b))
echo "The sum of $a and $b is $result"

# Register a tool to generate a QR code
mcp proxy tool qrcode "Generates a QR code" "text:string" \
  -e 'echo -e "data:image/png;base64,$(qrencode -t png -o - "$text" | base64 -w 0)"'

# Simple addition
mcp proxy tool add_op "Adds given numbers" "a:int,b:int" -e 'echo "total is $a + $b = $(($a+$b))"'

# Customized greeting
mcp proxy tool greet "Greets a user" "name:string,greeting:string,formal:bool" -e '
if [ "$formal" = "true" ]; then
  title="Mr./Ms."
  echo "${greeting:-Hello}, ${title} ${name}. How may I assist you today?"
else
  echo "${greeting:-Hello}, ${name}! Nice to meet you!"
fi
'

# File operations
mcp proxy tool count_lines "Counts lines in a file" "file:string" -e "wc -l  **Note:** Guard mode currently only works with STDIO transport (command execution) and not HTTP transport.

#### How It Works

The guard command works by:
1. Creating a proxy that sits between the client and the MCP server
2. Intercepting and filtering all requests to `tools/list`, `prompts/list`, and `resources/list`
3. Preventing calls to tools, prompts, or resources that don't match the allowed patterns
4. Blocking requests for filtered resources, tools and prompts
6. Passing through all other requests and responses unchanged

#### Pattern Matching

Patterns use simple glob syntax with `*` as a wildcard:

- `tools:read_*` - Matches all tools starting with "read_"
- `tools:*file*` - Matches any tool with "file" in the name
- `prompts:system_*` - Matches all prompts starting with "system_"

For each entity type, you can specify:
- `--allow 'pattern1,pattern2,...'` - Only allow entities matching these patterns
- `--deny 'pattern1,pattern2,...'` - Remove entities matching these patterns

If no allow patterns are specified, all entities are allowed by default (except those matching deny patterns).

#### Application Integration

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:

To:

This provides a read-only view of the filesystem by preventing any modification operations.

You can also use aliases with the guard command in configurations:

This makes your configurations even more concise and easier to maintain.

#### Logging

- Guard operations are logged to `~/.mcpt/logs/guard.log`
- The log includes all requests, responses, and filtering decisions
- Use `tail -f ~/.mcpt/logs/guard.log` to monitor activity in real-time

## Examples

### Basic Usage

List tools from a filesystem server:

Call a tool with pretty JSON output:

Use the guard mode to filter available tools:

### Streamable HTTP Usage

Create and run a local streamable HTTP server:

In a separate terminal, connect to your local server:

Connect to remote streamable HTTP servers:

### Script Integration

Using the proxy mode with a simple shell script:

### Debugging

Tailing the logs to debug your proxy or mock server:

## Contributing

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.

## Roadmap

The following features are planned for future releases:

- Authentication: Support for secure authentication mechanisms

## License

This project is licensed under the MIT License.

## Thanks

Thanks to [Fatih Taskiran](https://bsky.app/profile/fatih.co) for the logo design.