mcpctl

CLI for managing and interacting with MCP (Model Context Protocol) servers.

Installation

# From PyPI
pip install mcpctl

# With Redis support
pip install mcpctl[redis]

# With semantic search support
pip install mcpctl[semantic]

# For development
git clone https://github.com/thehumanworks/mcpctl
cd mcpctl
pip install -e .

Quick Start

# Add an HTTP server
mcpctl registry add myserver --transport http --url https://mcp.example.com

# Add a stdio server
mcpctl registry add local-server --transport stdio --cmd "npx my-mcp-server"

# List registered servers
mcpctl registry list

# Ping a server
mcpctl ping myserver

# List available tools
mcpctl tools myserver

# Call a tool
mcpctl call myserver my_tool --arg key=value --arg data:='{"nested": true}'

Environment Variables

Registry Storage

By default, mcpctl uses in-memory storage (non-persistent). Configure persistent storage with:

Variable	Description
MCPCTL_REGISTRY_DISK_PATH	Path to directory for disk-based storage
MCPCTL_REGISTRY_REDIS_URL	Redis URL for distributed storage (supports redis:// and rediss:// for SSL)

# Use disk storage
export MCPCTL_REGISTRY_DISK_PATH=~/.mcpctl

# Use Redis
export MCPCTL_REGISTRY_REDIS_URL=redis://localhost:6379/0

# Use Redis with SSL
export MCPCTL_REGISTRY_REDIS_URL=rediss://user:pass@redis.example.com:6379/0

Authentication

For servers using Bearer token authentication, set the token in an environment variable and reference it when adding the server:

export MY_API_TOKEN=sk-xxx
mcpctl registry add myserver --transport http --url https://api.example.com --bearer-env MY_API_TOKEN

Commands

Registry Management

# Add a server
mcpctl registry add <name> --transport <http|stdio> [options]

# HTTP transport options
--url <url>              # Server URL (required for http)
--oauth                  # Enable OAuth authentication
--bearer-env <var>       # Environment variable containing Bearer token

# Stdio transport options
--cmd <command>          # Command to run (required for stdio)
--cmd-args <args>        # Additional arguments (can be repeated)
--env <KEY=VALUE>        # Environment variables for the process
--cwd <path>             # Working directory

# List all servers
mcpctl registry list

# Show server config
mcpctl registry get <name>

# Remove a server
mcpctl registry delete <name>

Server Operations

# Test server connectivity
mcpctl ping <server>

# Authenticate (for OAuth servers)
mcpctl auth <server>

Tools

# List all tools
mcpctl tools <server>

# Show tool details
mcpctl tools <server> <tool_name>

# List as JSON
mcpctl tools <server> --json-out

# Call a tool
mcpctl call <server> <tool> [--arg key=value] [--arg key:=json]

Argument Syntax

• key=value - Auto-detects type (int, float, bool, null, string)
• key:=json - Explicit JSON parsing for objects/arrays

# String
--arg name=John

# Number (auto-detected)
--arg count=42

# Boolean
--arg enabled=true

# Explicit JSON object
--arg config:='{"timeout": 30}'

# Explicit JSON array
--arg items:='["a", "b", "c"]'

Resources

# List resources
mcpctl resources <server> --list

# List resource templates
mcpctl resources <server> --templates

# Read a resource
mcpctl resources <server> --uri <uri>

Prompts

# List prompts
mcpctl prompts <server> --list

# Get prompt details
mcpctl prompts <server> --name <prompt_name>

Discovery

# Discover tools across all servers
mcpctl discover

# Search for specific tools
mcpctl discover --query "search term"

Transport Types

HTTP

For remote MCP servers accessible via HTTP/HTTPS:

mcpctl registry add remote --transport http --url https://mcp.example.com

With OAuth:

mcpctl registry add oauth-server --transport http --url https://mcp.example.com --oauth
mcpctl auth oauth-server  # Complete OAuth flow

With Bearer token:

export API_KEY=your-token
mcpctl registry add api-server --transport http --url https://api.example.com --bearer-env API_KEY

Stdio

For local MCP servers that communicate via stdin/stdout:

# Simple command
mcpctl registry add local --transport stdio --cmd "my-mcp-server"

# With arguments
mcpctl registry add local --transport stdio --cmd my-mcp --cmd-args --port --cmd-args 8080

# Command with spaces (auto-split)
mcpctl registry add local --transport stdio --cmd "npx @modelcontextprotocol/server-filesystem /tmp"

# With environment variables
mcpctl registry add local --transport stdio --cmd my-mcp --env API_KEY=secret --env DEBUG=1

# With working directory
mcpctl registry add local --transport stdio --cmd ./server.py --cwd /path/to/project

License

MIT