mcpctl 0.1.0
CLI for managing and interacting with MCP (Model Context Protocol) servers
Requires Python: >=3.12
Keywords: mcp, model-context-protocol, cli, server, registry, tools, ai, llm

# mcpctl

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

## Installation

```bash
# 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

```bash
# 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) |

```bash
# 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:

```bash
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

```bash
# 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

```bash
# Test server connectivity
mcpctl ping <server>

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

### Tools

```bash
# 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

```bash
# 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

```bash
# List resources
mcpctl resources <server> --list

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

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

### Prompts

```bash
# List prompts
mcpctl prompts <server> --list

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

### Discovery

```bash
# 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:

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

With OAuth:

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

With Bearer token:

```bash
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:

```bash
# 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