# mcpsh
A clean, simple command-line interface for interacting with Model Context Protocol (MCP) servers using FastMCP.
**Transform any MCP server into a CLI tool** - perfect for AI agents, automation scripts, and manual operations. Get the rich ecosystem of MCP tools with the simplicity and universality of the command line.
## Features
- 🚀 **Simple & Fast** - Built with FastMCP for reliable MCP communication
- ⚡ **Zero Install** - Run with `uvx mcpsh` without installation
- 📋 **List & Discover** - Explore tools, resources, and prompts from any MCP server
- 🔍 **Schema Inspection** - View detailed tool schemas and parameter requirements
- 🔧 **Execute Tools** - Call MCP tools directly from the command line
- 📖 **Read Resources** - Access resource data with formatted output
- 🎯 **Clean Output** - Server logs suppressed by default for clean, parseable output
- 📝 **Flexible Formatting** - Output results in JSON or Markdown format
- ⚙️ **Config-Based** - Use standard MCP configuration format (compatible with Claude Desktop)
## Why CLI for MCP?
### 🤖 **Perfect for AI Agent Automation**
While MCP (Model Context Protocol) is powerful, exposing MCP servers through CLI offers critical advantages for AI/LLM agents:
**Reduced Context Overhead**
- MCP requires embedding **every tool's schema** into the LLM's context window
- As you add more MCP tools, the context bloats and model performance degrades
- CLI invocation is lean - just command names and simple arguments
- **Result**: Your AI agent can access more tools without hitting context limits
**Universal LLM Support**
- **Any LLM that can execute shell commands** can use these tools
- Works with Claude, GPT-4, local models, Cursor, Aider, and custom agents
- No need for MCP-specific integration or protocol support
- **Result**: Use the same tools across all your AI coding assistants
**Simpler, More Reliable Function Calling**
- LLMs generate CLI commands more reliably than complex protocol calls
- Familiar bash syntax reduces hallucination and errors
- Standard input/output makes debugging trivial
- **Result**: Higher success rates and fewer agent failures
**Use in Claude Skills & skill-mcp**
Claude Skills allow you to upload code that Claude can execute. However, **[skill-mcp](https://github.com/fkesheh/skill-mcp)** provides a superior approach using MCP:
- ✅ **Not locked to Claude** - Skills work in Claude, Cursor, and any MCP client
- ✅ **No manual uploads** - Manage skills programmatically via MCP
- ✅ **Better tool access** - Use `mcpsh` in your skills to access databases, APIs, monitoring tools, etc.
- ✅ **Universal & future-proof** - MCP protocol vs proprietary Claude feature
**Example skill using mcpsh:**
```python
# In a skill-mcp skill script
import subprocess
import json
# Query database using mcpsh
result = subprocess.run([
"mcpsh", "call", "postgres", "query",
"--args", '{"sql": "SELECT * FROM users WHERE active = true"}',
"-f", "json"
], capture_output=True, text=True)
data = json.loads(result.stdout.split('\n')[-2]) # Skip success message
# Process data...
```
**More AI Agent Examples:**
```bash
# AI coding assistant queries your database
mcpsh call postgres query --args '{"sql": "SELECT * FROM users WHERE active = true"}'
# AI ops agent checks production metrics
mcpsh call new-relic run_nrql_query --args '{"query_input": {"nrql": "SELECT count(*) FROM Transaction WHERE appName = 'api' SINCE 1 hour ago"}}'
# AI assistant manages your infrastructure
mcpsh call databricks list_clusters
mcpsh call skill-mcp run_skill_script --args '{"skill_name": "deploy", "script_path": "deploy.py"}'
```
### 🌉 **Bridge Between Worlds**
Get the **best of both**:
- Access the rich ecosystem of MCP servers (databases, APIs, monitoring, etc.)
- Use them with the simplicity and universality of CLI tools
- Perfect for [skill-mcp](https://github.com/fkesheh/skill-mcp) skills - combine MCP tool access with skill execution
- No need to choose - MCP servers become CLI tools!
## Quick Start
### Installation
```bash
# Option 1: Run directly with uvx (no installation required)
uvx mcpsh servers
uvx mcpsh call <server> <tool> --args '{...}'
# Option 2: Install from PyPI
pip install mcpsh
# or using uv
uv pip install mcpsh
# Option 3: Install from source
git clone https://github.com/fkesheh/mcpsh
cd mcpsh
uv pip install -e .
```
### Setup Configuration
#### Option 1: Use Existing Claude Desktop Config
If you already have Claude Desktop installed and configured, the CLI will automatically use it:
```bash
mcpsh servers
```
#### Option 2: Create Custom Configuration
Create a `~/.mcpsh/mcp_config.json` file in your home directory:
```bash
# Create the directory
mkdir -p ~/.mcpsh
# Create the config file
cat > ~/.mcpsh/mcp_config.json << 'EOF'
{
"mcpServers": {
"my-server": {
"command": "python",
"args": ["path/to/server.py"]
}
}
}
EOF
```
### Basic Workflow
```bash
# 1. List your servers
mcpsh servers
# 2. Explore a server
mcpsh info postgres
# 3. List available tools
mcpsh tools postgres
# 4. Get detailed info about a tool
mcpsh tool-info postgres query
# 5. Call a tool
mcpsh call postgres list_tables
# 6. Call a tool with arguments (output in Markdown format by default)
mcpsh call postgres query --args '{"sql": "SELECT * FROM users LIMIT 5"}'
# 7. Get results in JSON format
mcpsh call postgres query --args '{"sql": "SELECT * FROM users LIMIT 5"}' --format json
# 8. Verbose mode - show server logs (for debugging)
mcpsh tools postgres --verbose
```
## Configuration
### Default Configuration Locations
The CLI automatically looks for configuration in this order:
1. Path specified with `--config` flag
2. `~/.mcpsh/mcp_config.json` (recommended default location)
3. `~/Library/Application Support/Claude/claude_desktop_config.json` (Claude Desktop)
4. `~/.cursor/mcp.json` (Cursor MCP config)
### Configuration Format
The CLI supports the standard MCP configuration format:
```json
{
"mcpServers": {
"local-server": {
"command": "python",
"args": ["path/to/server.py"],
"env": {
"API_KEY": "your-api-key-here"
}
},
"remote-server": {
"url": "https://example.com/mcp",
"transport": "http",
"headers": {
"Authorization": "Bearer your-token-here"
}
},
"package-server": {
"command": "uvx",
"args": ["--from", "some-mcp-package", "mcp-server-command"]
}
}
}
```
## Commands
### List Servers
```bash
mcpsh servers [--config PATH] [--verbose]
```
Lists all configured MCP servers with their status.
**Options:**
- `--config`, `-c` - Path to MCP configuration file
- `--verbose`, `-v` - Show detailed server logs (suppressed by default)
### Show Server Info
```bash
mcpsh info <server-name> [--config PATH]
```
Shows detailed information about a server including:
- Server configuration
- Connection status
- Number of tools, resources, and prompts
### List Tools
```bash
mcpsh tools <server-name> [--config PATH] [--detailed] [--verbose]
```
Lists all available tools from a server with their descriptions.
**Options:**
- `--config`, `-c` - Path to MCP configuration file
- `--detailed`, `-d` - Show detailed information including input schemas for all tools
- `--verbose`, `-v` - Show detailed server logs (suppressed by default)
**Examples:**
```bash
# Simple list of tools (clean output by default)
mcpsh tools postgres
# Detailed view with input schemas
mcpsh tools postgres --detailed
# Show server logs for debugging
mcpsh tools postgres --verbose
```
### Get Tool Info
```bash
mcpsh tool-info <server-name> <tool-name> [--config PATH]
```
Shows detailed information about a specific tool including:
- Tool description
- Complete input schema (JSON Schema format)
- Parameter details (required/optional, types, descriptions)
- Example usage command
**Examples:**
```bash
# Get details about a specific tool
mcpsh tool-info new_relic_mcp run_nrql_query
# Check parameter requirements before calling a tool
mcpsh tool-info postgres query
```
### Call a Tool
```bash
mcpsh call <server-name> <tool-name> [--args JSON] [--format FORMAT] [--config PATH] [--verbose]
```
Executes a tool on an MCP server. Output is clean by default (server logs suppressed).
**Options:**
- `--args`, `-a` - Tool arguments as JSON string
- `--config`, `-c` - Path to MCP configuration file
- `--format`, `-f` - Output format: `markdown` (default) or `json`
- `--verbose`, `-v` - Show detailed server logs (suppressed by default)
**Examples:**
```bash
# Simple tool (no arguments)
mcpsh call postgres list_tables
# Tool with arguments
mcpsh call postgres query --args '{"sql": "SELECT * FROM users LIMIT 5"}'
# Complex nested arguments
mcpsh call shippo-new-relic-mcp run_nrql_query --args '{
"query_input": {
"nrql": "SELECT count(*) FROM Transaction SINCE 1 hour ago"
}
}'
# Output in Markdown format (default - more readable):
# ✓ Tool executed successfully
#
# results:
# • Item 1: count: 4246161
# query_id: null
# completed: true
# ...
# Output in JSON format (use --format json):
mcpsh call shippo-new-relic-mcp run_nrql_query --args '{
"query_input": {
"nrql": "SELECT count(*) FROM Transaction SINCE 1 hour ago"
}
}' --format json
# Or use shorthand:
mcpsh call postgres query --args '{"sql": "SELECT * FROM users"}' -f json
# Show server logs for debugging
mcpsh call postgres query --args '{"sql": "SELECT * FROM users"}' --verbose
```
### List Resources
```bash
mcpsh resources <server-name> [--config PATH]
```
Lists all available resources from a server.
### Read a Resource
```bash
mcpsh read <server-name> <resource-uri> [--config PATH]
```
Reads and displays the content of a resource.
**Examples:**
```bash
# Read static resource
mcpsh read example "data://example/info"
# Read templated resource
mcpsh read example "data://example/apple"
# Read skill documentation
mcpsh read skill-mcp "skill://data-analysis/SKILL.md"
```
### List Prompts
```bash
mcpsh prompts <server-name> [--config PATH]
```
Lists all available prompts from a server.
## Usage Examples
### Discovering Tool Schemas
Before calling a tool, you can inspect its input schema to understand what arguments it expects:
```bash
# Get detailed info about a specific tool
mcpsh tool-info new_relic_mcp run_nrql_query
# This shows:
# - Tool description
# - Complete JSON schema
# - Parameter details (required/optional)
# - Example usage command
# Now use the tool with correct arguments
mcpsh call new_relic_mcp run_nrql_query --args '{
"query_input": {
"nrql": "SELECT count(*) FROM Transaction SINCE 1 hour ago"
}
}'
```
### Database Operations
```bash
# List database tables
mcpsh call postgres list_tables
# Get table structure
mcpsh call postgres describe_table --args '{"table": "users"}'
# Run a query
mcpsh call postgres query --args '{
"sql": "SELECT name, email FROM users WHERE active = true ORDER BY created_at DESC LIMIT 5"
}'
# Count records
mcpsh call postgres query --args '{
"sql": "SELECT COUNT(*) as total FROM orders WHERE status = '\''completed'\''"
}'
```
### Skill Management with skill-mcp
[skill-mcp](https://github.com/fkesheh/skill-mcp) is an MCP server that lets you create, manage, and execute skills programmatically. It's superior to Claude Skills because it:
- ✅ Works in Claude, Cursor, and any MCP client (not locked to Claude)
- ✅ No manual file uploads - manage skills via MCP protocol
- ✅ Skills can use `mcpsh` to access any MCP server (databases, APIs, etc.)
- ✅ Local-first, future-proof, and open standard
**Managing Skills:**
```bash
# List available skills
mcpsh tools skill-mcp
# Read skill documentation
mcpsh read skill-mcp "skill://data-analysis/SKILL.md"
# Get skill details
mcpsh call skill-mcp get_skill_details --args '{"skill_name": "data-processor"}'
# Execute a skill script
mcpsh call skill-mcp run_skill_script --args '{
"skill_name": "data-processor",
"script_path": "scripts/process.py",
"args": ["--input", "data/input.csv", "--output", "data/output.json"]
}'
```
**Using mcpsh Inside Skills:**
Skills can use `mcpsh` to access any MCP server, giving them superpowers:
```python
# Example: skill that queries database and sends alerts
# ~/.skill-mcp/skills/db-monitor/scripts/check_health.py
import subprocess
import json
def run_mcpsh(server, tool, args):
"""Helper to run mcpsh and parse JSON output"""
result = subprocess.run([
"mcpsh", "call", server, tool,
"--args", json.dumps(args),
"-f", "json"
], capture_output=True, text=True)
# Skip success message, get JSON
output = result.stdout.strip().split('\n')[-1]
return json.loads(output)
# Query database
users = run_mcpsh("postgres", "query", {
"sql": "SELECT COUNT(*) as count FROM users WHERE last_login < NOW() - INTERVAL '30 days'"
})
# Check metrics
metrics = run_mcpsh("new-relic", "run_nrql_query", {
"query_input": {
"nrql": "SELECT average(duration) FROM Transaction SINCE 1 hour ago"
}
})
# Send alert if needed
if users['count'] > 100:
print(f"Alert: {users['count']} inactive users found")
```
This approach gives your skills access to:
- Databases (PostgreSQL, MySQL, etc.)
- Monitoring tools (New Relic, Datadog, etc.)
- Cloud platforms (Databricks, AWS, etc.)
- Any MCP server in your config!
### API Exploration
```bash
# List API explorer capabilities
mcpsh tools api-explorer
# Make a GET request
mcpsh call api-explorer make_request --args '{
"url": "https://jsonplaceholder.typicode.com/posts/1",
"method": "GET"
}'
# Make a POST request
mcpsh call api-explorer make_request --args '{
"url": "https://api.example.com/data",
"method": "POST",
"body": {"title": "New Item", "completed": false},
"headers": {"Content-Type": "application/json"}
}'
```
### Monitoring with New Relic
```bash
# List available monitoring tools
mcpsh tools new_relic_mcp
# Query application metrics
mcpsh call new_relic_mcp query_nrql --args '{
"query": "SELECT average(duration) FROM Transaction WHERE appName = '\''MyApp'\'' SINCE 1 hour ago"
}'
# Get service health
mcpsh call new_relic_mcp get_service_health --args '{
"service_name": "api-gateway"
}'
```
### Scripting and Automation
The CLI has clean output by default, making it perfect for scripts and automation.
```bash
# Clean output - ready for scripting
mcpsh call shippo-new-relic-mcp run_nrql_query \
--args '{"query_input":{"nrql":"SELECT count(*) FROM Transaction SINCE 1 hour ago"}}'
# Parse JSON output with jq (skip success message)
RESULT=$(mcpsh call shippo-new-relic-mcp run_nrql_query \
--args '{"query_input":{"nrql":"SELECT count(*) FROM Transaction SINCE 1 hour ago"}}' \
| tail -n +3) # Skip success message and blank line
echo "$RESULT" | jq -r '.results[0].count'
# Use in a bash script
#!/bin/bash
TRANSACTION_COUNT=$(mcpsh call shippo-new-relic-mcp run_nrql_query \
--args '{"query_input":{"nrql":"SELECT count(*) FROM Transaction SINCE 1 hour ago"}}' \
| tail -n +3 | jq -r '.results[0].count')
echo "Total transactions: $TRANSACTION_COUNT"
# Error handling in scripts
if OUTPUT=$(mcpsh call postgres query \
--args '{"sql": "SELECT COUNT(*) FROM users"}'); then
echo "Success: $OUTPUT"
else
echo "Failed to query database"
exit 1
fi
```
**Tips for Scripting:**
- Output is clean by default (no server logs or fancy formatting)
- Use `tail -n +3` to skip the success message if you only want the JSON
- Pipe to `jq` for JSON parsing and extraction
- Check exit codes for error handling
- Use `--verbose` flag only when debugging issues
## Advanced Usage
### Custom Configuration Files
```bash
# Development configuration
mcpsh servers --config ./config/dev.json
# Production configuration
mcpsh servers --config ./config/prod.json
# Testing with example server
mcpsh tools example --config ./example_config.json
```
### Piping and Automation
```bash
# Save tool output to file
mcpsh call postgres query --args '{"sql": "SELECT * FROM users"}' > users.txt
# Use in scripts
#!/bin/bash
TABLES=$(mcpsh call postgres list_tables --args '{}')
echo "Database has these tables: $TABLES"
# Process with other tools
mcpsh call postgres query --args '{"sql": "SELECT * FROM metrics"}' | jq '.[] | select(.value > 100)'
```
### Working with Different Server Types
```bash
# Local Python servers
mcpsh tools example --config example_config.json
# Remote HTTP servers (configure with "url" and "transport": "http")
mcpsh tools remote-api
# NPX/UVX servers (configure with "command": "uvx" or "npx")
mcpsh tools mcp-package-server
```
## Example Server
The repository includes an example MCP server for testing:
### Running the Example
```bash
# In one terminal, start the example server:
python example_server.py
# In another terminal, use the CLI:
mcpsh tools example --config example_config.json
mcpsh call example greet --args '{"name": "World"}'
mcpsh call example add --args '{"a": 5, "b": 3}'
mcpsh resources example --config example_config.json
mcpsh read example "data://example/apple" --config example_config.json
```
The example server provides:
- **Tools**: `greet`, `add`, `multiply`
- **Resources**: `data://example/info`, `data://example/{item}` (template)
- **Prompts**: `analyze_data`
## Troubleshooting
### "Server not found"
Make sure the server name matches exactly what's in your configuration:
```bash
# List servers to see exact names
mcpsh servers
```
### "Tool not found"
List tools to see the exact name (some servers add prefixes):
```bash
mcpsh tools <server-name>
# Note: Multi-server configs may prefix tool names
# Example: "servername_toolname"
```
### "Invalid JSON"
Ensure your arguments are valid JSON with proper quoting:
```bash
# ✓ Good - single quotes outside, double quotes inside
mcpsh call server tool --args '{"key": "value"}'
# ✗ Bad - missing quotes
mcpsh call server tool --args '{key: value}'
```
### Connection Issues
```bash
# Test server connectivity
mcpsh info <server-name>
# This will show if the server is responding and any errors
```
## Tips and Best Practices
1. **Check tool names first**: Use `mcpsh tools <server>` to see exact names and descriptions
2. **Use valid JSON for arguments**: Single quotes around the JSON, double quotes inside
3. **Start simple**: Test with `servers` and `info` before calling tools
4. **Read descriptions**: Tool and resource descriptions often include usage hints
5. **Test with example server**: Use `example_config.json` to verify the CLI is working
6. **Use custom configs**: Separate configs for different environments (dev, staging, prod)
## Command Reference
| Command | Description | Example |
|---------|-------------|---------|
| `servers` | List all configured servers | `mcpsh servers` |
| `info` | Show server details | `mcpsh info postgres` |
| `tools` | List tools from a server | `mcpsh tools postgres` |
| `call` | Execute a tool | `mcpsh call postgres query --args '{"sql":"..."}` |
| `resources` | List resources from a server | `mcpsh resources skill-mcp` |
| `read` | Read a resource | `mcpsh read skill-mcp "skill://..."` |
| `prompts` | List prompts from a server | `mcpsh prompts server-name` |
## Common Patterns
### Exploration Pattern
```bash
# 1. See what servers are available
mcpsh servers
# 2. Check what a server offers
mcpsh info postgres
# 3. Look at specific capabilities
mcpsh tools postgres
mcpsh resources postgres
mcpsh prompts postgres
# 4. Try it out
mcpsh call postgres list_tables
```
### Integration Pattern
```bash
# Use MCP CLI in larger workflows
#!/bin/bash
# Get data from MCP server
DATA=$(mcpsh call postgres query --args '{"sql": "SELECT * FROM metrics"}')
# Process with other tools
echo "$DATA" | jq '.[] | select(.value > 100)'
# Store results
mcpsh call postgres query --args '{"sql": "..."}' > output.json
```
## Getting Help
```bash
# General help
mcpsh --help
# Command-specific help
mcpsh servers --help
mcpsh call --help
mcpsh tools --help
```
## Requirements
- Python 3.10+
- FastMCP 2.12.5+
- Typer 0.20.0+
- Rich 14.2.0+
## Development
### Project Structure
```
mcpsh/
├── src/
│ └── mcp_cli/
│ ├── __init__.py
│ ├── main.py # CLI commands
│ └── config.py # Configuration loader
├── example_server.py # Example MCP server for testing
├── example_config.json # Example configuration
├── pyproject.toml
└── README.md
```
### Running in Development
```bash
# Install in editable mode
uv pip install -e .
# Run the CLI
mcpsh --help
# Test with example server
python example_server.py # In one terminal
mcpsh tools example --config example_config.json # In another
```
## Related Projects
- [FastMCP](https://gofastmcp.com) - The framework used to build this CLI
- [Model Context Protocol](https://modelcontextprotocol.io/) - Official MCP specification
- [Claude Desktop](https://claude.ai/download) - Uses the same configuration format
## License
MIT
## Contributing
Contributions welcome! This is a simple tool focused on making MCP server interaction easy from the command line.
Raw data
{
"_id": null,
"home_page": null,
"name": "mcpsh",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.10",
"maintainer_email": null,
"keywords": "mcp, model-context-protocol, cli, fastmcp, tools",
"author": "Foad Kesheh",
"author_email": null,
"download_url": "https://files.pythonhosted.org/packages/2e/db/493bf9f8a69daac1831104721029eb493787ee70c628e258fde9aace8bcc/mcpsh-0.1.3.tar.gz",
"platform": null,
"description": "# mcpsh\n\nA clean, simple command-line interface for interacting with Model Context Protocol (MCP) servers using FastMCP.\n\n**Transform any MCP server into a CLI tool** - perfect for AI agents, automation scripts, and manual operations. Get the rich ecosystem of MCP tools with the simplicity and universality of the command line.\n\n## Features\n\n- \ud83d\ude80 **Simple & Fast** - Built with FastMCP for reliable MCP communication\n- \u26a1 **Zero Install** - Run with `uvx mcpsh` without installation\n- \ud83d\udccb **List & Discover** - Explore tools, resources, and prompts from any MCP server\n- \ud83d\udd0d **Schema Inspection** - View detailed tool schemas and parameter requirements\n- \ud83d\udd27 **Execute Tools** - Call MCP tools directly from the command line\n- \ud83d\udcd6 **Read Resources** - Access resource data with formatted output\n- \ud83c\udfaf **Clean Output** - Server logs suppressed by default for clean, parseable output\n- \ud83d\udcdd **Flexible Formatting** - Output results in JSON or Markdown format\n- \u2699\ufe0f **Config-Based** - Use standard MCP configuration format (compatible with Claude Desktop)\n\n## Why CLI for MCP?\n\n### \ud83e\udd16 **Perfect for AI Agent Automation**\n\nWhile MCP (Model Context Protocol) is powerful, exposing MCP servers through CLI offers critical advantages for AI/LLM agents:\n\n**Reduced Context Overhead**\n- MCP requires embedding **every tool's schema** into the LLM's context window\n- As you add more MCP tools, the context bloats and model performance degrades\n- CLI invocation is lean - just command names and simple arguments\n- **Result**: Your AI agent can access more tools without hitting context limits\n\n**Universal LLM Support** \n- **Any LLM that can execute shell commands** can use these tools\n- Works with Claude, GPT-4, local models, Cursor, Aider, and custom agents\n- No need for MCP-specific integration or protocol support\n- **Result**: Use the same tools across all your AI coding assistants\n\n**Simpler, More Reliable Function Calling**\n- LLMs generate CLI commands more reliably than complex protocol calls\n- Familiar bash syntax reduces hallucination and errors\n- Standard input/output makes debugging trivial\n- **Result**: Higher success rates and fewer agent failures\n\n**Use in Claude Skills & skill-mcp**\n\nClaude Skills allow you to upload code that Claude can execute. However, **[skill-mcp](https://github.com/fkesheh/skill-mcp)** provides a superior approach using MCP:\n\n- \u2705 **Not locked to Claude** - Skills work in Claude, Cursor, and any MCP client\n- \u2705 **No manual uploads** - Manage skills programmatically via MCP\n- \u2705 **Better tool access** - Use `mcpsh` in your skills to access databases, APIs, monitoring tools, etc.\n- \u2705 **Universal & future-proof** - MCP protocol vs proprietary Claude feature\n\n**Example skill using mcpsh:**\n\n```python\n# In a skill-mcp skill script\nimport subprocess\nimport json\n\n# Query database using mcpsh\nresult = subprocess.run([\n \"mcpsh\", \"call\", \"postgres\", \"query\",\n \"--args\", '{\"sql\": \"SELECT * FROM users WHERE active = true\"}',\n \"-f\", \"json\"\n], capture_output=True, text=True)\n\ndata = json.loads(result.stdout.split('\\n')[-2]) # Skip success message\n# Process data...\n```\n\n**More AI Agent Examples:**\n\n```bash\n# AI coding assistant queries your database\nmcpsh call postgres query --args '{\"sql\": \"SELECT * FROM users WHERE active = true\"}'\n\n# AI ops agent checks production metrics \nmcpsh call new-relic run_nrql_query --args '{\"query_input\": {\"nrql\": \"SELECT count(*) FROM Transaction WHERE appName = 'api' SINCE 1 hour ago\"}}'\n\n# AI assistant manages your infrastructure\nmcpsh call databricks list_clusters\nmcpsh call skill-mcp run_skill_script --args '{\"skill_name\": \"deploy\", \"script_path\": \"deploy.py\"}'\n```\n\n### \ud83c\udf09 **Bridge Between Worlds**\n\nGet the **best of both**:\n- Access the rich ecosystem of MCP servers (databases, APIs, monitoring, etc.)\n- Use them with the simplicity and universality of CLI tools \n- Perfect for [skill-mcp](https://github.com/fkesheh/skill-mcp) skills - combine MCP tool access with skill execution\n- No need to choose - MCP servers become CLI tools!\n\n## Quick Start\n\n### Installation\n\n```bash\n# Option 1: Run directly with uvx (no installation required)\nuvx mcpsh servers\nuvx mcpsh call <server> <tool> --args '{...}'\n\n# Option 2: Install from PyPI\npip install mcpsh\n# or using uv\nuv pip install mcpsh\n\n# Option 3: Install from source\ngit clone https://github.com/fkesheh/mcpsh\ncd mcpsh\nuv pip install -e .\n```\n\n### Setup Configuration\n\n#### Option 1: Use Existing Claude Desktop Config\n\nIf you already have Claude Desktop installed and configured, the CLI will automatically use it:\n\n```bash\nmcpsh servers\n```\n\n#### Option 2: Create Custom Configuration\n\nCreate a `~/.mcpsh/mcp_config.json` file in your home directory:\n\n```bash\n# Create the directory\nmkdir -p ~/.mcpsh\n\n# Create the config file\ncat > ~/.mcpsh/mcp_config.json << 'EOF'\n{\n \"mcpServers\": {\n \"my-server\": {\n \"command\": \"python\",\n \"args\": [\"path/to/server.py\"]\n }\n }\n}\nEOF\n```\n\n### Basic Workflow\n\n```bash\n# 1. List your servers\nmcpsh servers\n\n# 2. Explore a server\nmcpsh info postgres\n\n# 3. List available tools\nmcpsh tools postgres\n\n# 4. Get detailed info about a tool\nmcpsh tool-info postgres query\n\n# 5. Call a tool\nmcpsh call postgres list_tables\n\n# 6. Call a tool with arguments (output in Markdown format by default)\nmcpsh call postgres query --args '{\"sql\": \"SELECT * FROM users LIMIT 5\"}'\n\n# 7. Get results in JSON format\nmcpsh call postgres query --args '{\"sql\": \"SELECT * FROM users LIMIT 5\"}' --format json\n\n# 8. Verbose mode - show server logs (for debugging)\nmcpsh tools postgres --verbose\n```\n\n## Configuration\n\n### Default Configuration Locations\n\nThe CLI automatically looks for configuration in this order:\n1. Path specified with `--config` flag\n2. `~/.mcpsh/mcp_config.json` (recommended default location)\n3. `~/Library/Application Support/Claude/claude_desktop_config.json` (Claude Desktop)\n4. `~/.cursor/mcp.json` (Cursor MCP config)\n\n### Configuration Format\n\nThe CLI supports the standard MCP configuration format:\n\n```json\n{\n \"mcpServers\": {\n \"local-server\": {\n \"command\": \"python\",\n \"args\": [\"path/to/server.py\"],\n \"env\": {\n \"API_KEY\": \"your-api-key-here\"\n }\n },\n \"remote-server\": {\n \"url\": \"https://example.com/mcp\",\n \"transport\": \"http\",\n \"headers\": {\n \"Authorization\": \"Bearer your-token-here\"\n }\n },\n \"package-server\": {\n \"command\": \"uvx\",\n \"args\": [\"--from\", \"some-mcp-package\", \"mcp-server-command\"]\n }\n }\n}\n```\n\n## Commands\n\n### List Servers\n\n```bash\nmcpsh servers [--config PATH] [--verbose]\n```\n\nLists all configured MCP servers with their status.\n\n**Options:**\n- `--config`, `-c` - Path to MCP configuration file\n- `--verbose`, `-v` - Show detailed server logs (suppressed by default)\n\n### Show Server Info\n\n```bash\nmcpsh info <server-name> [--config PATH]\n```\n\nShows detailed information about a server including:\n- Server configuration\n- Connection status\n- Number of tools, resources, and prompts\n\n### List Tools\n\n```bash\nmcpsh tools <server-name> [--config PATH] [--detailed] [--verbose]\n```\n\nLists all available tools from a server with their descriptions.\n\n**Options:**\n- `--config`, `-c` - Path to MCP configuration file\n- `--detailed`, `-d` - Show detailed information including input schemas for all tools\n- `--verbose`, `-v` - Show detailed server logs (suppressed by default)\n\n**Examples:**\n\n```bash\n# Simple list of tools (clean output by default)\nmcpsh tools postgres\n\n# Detailed view with input schemas\nmcpsh tools postgres --detailed\n\n# Show server logs for debugging\nmcpsh tools postgres --verbose\n```\n\n### Get Tool Info\n\n```bash\nmcpsh tool-info <server-name> <tool-name> [--config PATH]\n```\n\nShows detailed information about a specific tool including:\n- Tool description\n- Complete input schema (JSON Schema format)\n- Parameter details (required/optional, types, descriptions)\n- Example usage command\n\n**Examples:**\n\n```bash\n# Get details about a specific tool\nmcpsh tool-info new_relic_mcp run_nrql_query\n\n# Check parameter requirements before calling a tool\nmcpsh tool-info postgres query\n```\n\n### Call a Tool\n\n```bash\nmcpsh call <server-name> <tool-name> [--args JSON] [--format FORMAT] [--config PATH] [--verbose]\n```\n\nExecutes a tool on an MCP server. Output is clean by default (server logs suppressed).\n\n**Options:**\n- `--args`, `-a` - Tool arguments as JSON string\n- `--config`, `-c` - Path to MCP configuration file\n- `--format`, `-f` - Output format: `markdown` (default) or `json`\n- `--verbose`, `-v` - Show detailed server logs (suppressed by default)\n\n**Examples:**\n\n```bash\n# Simple tool (no arguments)\nmcpsh call postgres list_tables\n\n# Tool with arguments\nmcpsh call postgres query --args '{\"sql\": \"SELECT * FROM users LIMIT 5\"}'\n\n# Complex nested arguments\nmcpsh call shippo-new-relic-mcp run_nrql_query --args '{\n \"query_input\": {\n \"nrql\": \"SELECT count(*) FROM Transaction SINCE 1 hour ago\"\n }\n}'\n\n# Output in Markdown format (default - more readable):\n# \u2713 Tool executed successfully\n# \n# results:\n# \u2022 Item 1: count: 4246161\n# query_id: null\n# completed: true\n# ...\n\n# Output in JSON format (use --format json):\nmcpsh call shippo-new-relic-mcp run_nrql_query --args '{\n \"query_input\": {\n \"nrql\": \"SELECT count(*) FROM Transaction SINCE 1 hour ago\"\n }\n}' --format json\n\n# Or use shorthand:\nmcpsh call postgres query --args '{\"sql\": \"SELECT * FROM users\"}' -f json\n\n# Show server logs for debugging\nmcpsh call postgres query --args '{\"sql\": \"SELECT * FROM users\"}' --verbose\n```\n\n### List Resources\n\n```bash\nmcpsh resources <server-name> [--config PATH]\n```\n\nLists all available resources from a server.\n\n### Read a Resource\n\n```bash\nmcpsh read <server-name> <resource-uri> [--config PATH]\n```\n\nReads and displays the content of a resource.\n\n**Examples:**\n\n```bash\n# Read static resource\nmcpsh read example \"data://example/info\"\n\n# Read templated resource\nmcpsh read example \"data://example/apple\"\n\n# Read skill documentation\nmcpsh read skill-mcp \"skill://data-analysis/SKILL.md\"\n```\n\n### List Prompts\n\n```bash\nmcpsh prompts <server-name> [--config PATH]\n```\n\nLists all available prompts from a server.\n\n## Usage Examples\n\n### Discovering Tool Schemas\n\nBefore calling a tool, you can inspect its input schema to understand what arguments it expects:\n\n```bash\n# Get detailed info about a specific tool\nmcpsh tool-info new_relic_mcp run_nrql_query\n\n# This shows:\n# - Tool description\n# - Complete JSON schema\n# - Parameter details (required/optional)\n# - Example usage command\n\n# Now use the tool with correct arguments\nmcpsh call new_relic_mcp run_nrql_query --args '{\n \"query_input\": {\n \"nrql\": \"SELECT count(*) FROM Transaction SINCE 1 hour ago\"\n }\n}'\n```\n\n### Database Operations\n\n```bash\n# List database tables\nmcpsh call postgres list_tables\n\n# Get table structure\nmcpsh call postgres describe_table --args '{\"table\": \"users\"}'\n\n# Run a query\nmcpsh call postgres query --args '{\n \"sql\": \"SELECT name, email FROM users WHERE active = true ORDER BY created_at DESC LIMIT 5\"\n}'\n\n# Count records\nmcpsh call postgres query --args '{\n \"sql\": \"SELECT COUNT(*) as total FROM orders WHERE status = '\\''completed'\\''\"\n}'\n```\n\n### Skill Management with skill-mcp\n\n[skill-mcp](https://github.com/fkesheh/skill-mcp) is an MCP server that lets you create, manage, and execute skills programmatically. It's superior to Claude Skills because it:\n\n- \u2705 Works in Claude, Cursor, and any MCP client (not locked to Claude)\n- \u2705 No manual file uploads - manage skills via MCP protocol\n- \u2705 Skills can use `mcpsh` to access any MCP server (databases, APIs, etc.)\n- \u2705 Local-first, future-proof, and open standard\n\n**Managing Skills:**\n\n```bash\n# List available skills\nmcpsh tools skill-mcp\n\n# Read skill documentation\nmcpsh read skill-mcp \"skill://data-analysis/SKILL.md\"\n\n# Get skill details\nmcpsh call skill-mcp get_skill_details --args '{\"skill_name\": \"data-processor\"}'\n\n# Execute a skill script\nmcpsh call skill-mcp run_skill_script --args '{\n \"skill_name\": \"data-processor\",\n \"script_path\": \"scripts/process.py\",\n \"args\": [\"--input\", \"data/input.csv\", \"--output\", \"data/output.json\"]\n}'\n```\n\n**Using mcpsh Inside Skills:**\n\nSkills can use `mcpsh` to access any MCP server, giving them superpowers:\n\n```python\n# Example: skill that queries database and sends alerts\n# ~/.skill-mcp/skills/db-monitor/scripts/check_health.py\n\nimport subprocess\nimport json\n\ndef run_mcpsh(server, tool, args):\n \"\"\"Helper to run mcpsh and parse JSON output\"\"\"\n result = subprocess.run([\n \"mcpsh\", \"call\", server, tool,\n \"--args\", json.dumps(args),\n \"-f\", \"json\"\n ], capture_output=True, text=True)\n \n # Skip success message, get JSON\n output = result.stdout.strip().split('\\n')[-1]\n return json.loads(output)\n\n# Query database\nusers = run_mcpsh(\"postgres\", \"query\", {\n \"sql\": \"SELECT COUNT(*) as count FROM users WHERE last_login < NOW() - INTERVAL '30 days'\"\n})\n\n# Check metrics\nmetrics = run_mcpsh(\"new-relic\", \"run_nrql_query\", {\n \"query_input\": {\n \"nrql\": \"SELECT average(duration) FROM Transaction SINCE 1 hour ago\"\n }\n})\n\n# Send alert if needed\nif users['count'] > 100:\n print(f\"Alert: {users['count']} inactive users found\")\n```\n\nThis approach gives your skills access to:\n- Databases (PostgreSQL, MySQL, etc.)\n- Monitoring tools (New Relic, Datadog, etc.)\n- Cloud platforms (Databricks, AWS, etc.)\n- Any MCP server in your config!\n\n### API Exploration\n\n```bash\n# List API explorer capabilities\nmcpsh tools api-explorer\n\n# Make a GET request\nmcpsh call api-explorer make_request --args '{\n \"url\": \"https://jsonplaceholder.typicode.com/posts/1\",\n \"method\": \"GET\"\n}'\n\n# Make a POST request\nmcpsh call api-explorer make_request --args '{\n \"url\": \"https://api.example.com/data\",\n \"method\": \"POST\",\n \"body\": {\"title\": \"New Item\", \"completed\": false},\n \"headers\": {\"Content-Type\": \"application/json\"}\n}'\n```\n\n### Monitoring with New Relic\n\n```bash\n# List available monitoring tools\nmcpsh tools new_relic_mcp\n\n# Query application metrics\nmcpsh call new_relic_mcp query_nrql --args '{\n \"query\": \"SELECT average(duration) FROM Transaction WHERE appName = '\\''MyApp'\\'' SINCE 1 hour ago\"\n}'\n\n# Get service health\nmcpsh call new_relic_mcp get_service_health --args '{\n \"service_name\": \"api-gateway\"\n}'\n```\n\n### Scripting and Automation\n\nThe CLI has clean output by default, making it perfect for scripts and automation.\n\n```bash\n# Clean output - ready for scripting\nmcpsh call shippo-new-relic-mcp run_nrql_query \\\n --args '{\"query_input\":{\"nrql\":\"SELECT count(*) FROM Transaction SINCE 1 hour ago\"}}'\n\n# Parse JSON output with jq (skip success message)\nRESULT=$(mcpsh call shippo-new-relic-mcp run_nrql_query \\\n --args '{\"query_input\":{\"nrql\":\"SELECT count(*) FROM Transaction SINCE 1 hour ago\"}}' \\\n | tail -n +3) # Skip success message and blank line\n \necho \"$RESULT\" | jq -r '.results[0].count'\n\n# Use in a bash script\n#!/bin/bash\nTRANSACTION_COUNT=$(mcpsh call shippo-new-relic-mcp run_nrql_query \\\n --args '{\"query_input\":{\"nrql\":\"SELECT count(*) FROM Transaction SINCE 1 hour ago\"}}' \\\n | tail -n +3 | jq -r '.results[0].count')\n\necho \"Total transactions: $TRANSACTION_COUNT\"\n\n# Error handling in scripts\nif OUTPUT=$(mcpsh call postgres query \\\n --args '{\"sql\": \"SELECT COUNT(*) FROM users\"}'); then\n echo \"Success: $OUTPUT\"\nelse\n echo \"Failed to query database\"\n exit 1\nfi\n```\n\n**Tips for Scripting:**\n- Output is clean by default (no server logs or fancy formatting)\n- Use `tail -n +3` to skip the success message if you only want the JSON\n- Pipe to `jq` for JSON parsing and extraction\n- Check exit codes for error handling\n- Use `--verbose` flag only when debugging issues\n\n## Advanced Usage\n\n### Custom Configuration Files\n\n```bash\n# Development configuration\nmcpsh servers --config ./config/dev.json\n\n# Production configuration \nmcpsh servers --config ./config/prod.json\n\n# Testing with example server\nmcpsh tools example --config ./example_config.json\n```\n\n### Piping and Automation\n\n```bash\n# Save tool output to file\nmcpsh call postgres query --args '{\"sql\": \"SELECT * FROM users\"}' > users.txt\n\n# Use in scripts\n#!/bin/bash\nTABLES=$(mcpsh call postgres list_tables --args '{}')\necho \"Database has these tables: $TABLES\"\n\n# Process with other tools\nmcpsh call postgres query --args '{\"sql\": \"SELECT * FROM metrics\"}' | jq '.[] | select(.value > 100)'\n```\n\n### Working with Different Server Types\n\n```bash\n# Local Python servers\nmcpsh tools example --config example_config.json\n\n# Remote HTTP servers (configure with \"url\" and \"transport\": \"http\")\nmcpsh tools remote-api\n\n# NPX/UVX servers (configure with \"command\": \"uvx\" or \"npx\")\nmcpsh tools mcp-package-server\n```\n\n## Example Server\n\nThe repository includes an example MCP server for testing:\n\n### Running the Example\n\n```bash\n# In one terminal, start the example server:\npython example_server.py\n\n# In another terminal, use the CLI:\nmcpsh tools example --config example_config.json\nmcpsh call example greet --args '{\"name\": \"World\"}'\nmcpsh call example add --args '{\"a\": 5, \"b\": 3}'\nmcpsh resources example --config example_config.json\nmcpsh read example \"data://example/apple\" --config example_config.json\n```\n\nThe example server provides:\n- **Tools**: `greet`, `add`, `multiply`\n- **Resources**: `data://example/info`, `data://example/{item}` (template)\n- **Prompts**: `analyze_data`\n\n## Troubleshooting\n\n### \"Server not found\"\n\nMake sure the server name matches exactly what's in your configuration:\n\n```bash\n# List servers to see exact names\nmcpsh servers\n```\n\n### \"Tool not found\"\n\nList tools to see the exact name (some servers add prefixes):\n\n```bash\nmcpsh tools <server-name>\n\n# Note: Multi-server configs may prefix tool names\n# Example: \"servername_toolname\"\n```\n\n### \"Invalid JSON\"\n\nEnsure your arguments are valid JSON with proper quoting:\n\n```bash\n# \u2713 Good - single quotes outside, double quotes inside\nmcpsh call server tool --args '{\"key\": \"value\"}'\n\n# \u2717 Bad - missing quotes\nmcpsh call server tool --args '{key: value}'\n```\n\n### Connection Issues\n\n```bash\n# Test server connectivity\nmcpsh info <server-name>\n\n# This will show if the server is responding and any errors\n```\n\n## Tips and Best Practices\n\n1. **Check tool names first**: Use `mcpsh tools <server>` to see exact names and descriptions\n2. **Use valid JSON for arguments**: Single quotes around the JSON, double quotes inside\n3. **Start simple**: Test with `servers` and `info` before calling tools\n4. **Read descriptions**: Tool and resource descriptions often include usage hints\n5. **Test with example server**: Use `example_config.json` to verify the CLI is working\n6. **Use custom configs**: Separate configs for different environments (dev, staging, prod)\n\n## Command Reference\n\n| Command | Description | Example |\n|---------|-------------|---------|\n| `servers` | List all configured servers | `mcpsh servers` |\n| `info` | Show server details | `mcpsh info postgres` |\n| `tools` | List tools from a server | `mcpsh tools postgres` |\n| `call` | Execute a tool | `mcpsh call postgres query --args '{\"sql\":\"...\"}` |\n| `resources` | List resources from a server | `mcpsh resources skill-mcp` |\n| `read` | Read a resource | `mcpsh read skill-mcp \"skill://...\"` |\n| `prompts` | List prompts from a server | `mcpsh prompts server-name` |\n\n## Common Patterns\n\n### Exploration Pattern\n\n```bash\n# 1. See what servers are available\nmcpsh servers\n\n# 2. Check what a server offers\nmcpsh info postgres\n\n# 3. Look at specific capabilities\nmcpsh tools postgres\nmcpsh resources postgres\nmcpsh prompts postgres\n\n# 4. Try it out\nmcpsh call postgres list_tables\n```\n\n### Integration Pattern\n\n```bash\n# Use MCP CLI in larger workflows\n#!/bin/bash\n\n# Get data from MCP server\nDATA=$(mcpsh call postgres query --args '{\"sql\": \"SELECT * FROM metrics\"}')\n\n# Process with other tools\necho \"$DATA\" | jq '.[] | select(.value > 100)'\n\n# Store results\nmcpsh call postgres query --args '{\"sql\": \"...\"}' > output.json\n```\n\n## Getting Help\n\n```bash\n# General help\nmcpsh --help\n\n# Command-specific help\nmcpsh servers --help\nmcpsh call --help\nmcpsh tools --help\n```\n\n## Requirements\n\n- Python 3.10+\n- FastMCP 2.12.5+\n- Typer 0.20.0+\n- Rich 14.2.0+\n\n## Development\n\n### Project Structure\n\n```\nmcpsh/\n\u251c\u2500\u2500 src/\n\u2502 \u2514\u2500\u2500 mcp_cli/\n\u2502 \u251c\u2500\u2500 __init__.py\n\u2502 \u251c\u2500\u2500 main.py # CLI commands\n\u2502 \u2514\u2500\u2500 config.py # Configuration loader\n\u251c\u2500\u2500 example_server.py # Example MCP server for testing\n\u251c\u2500\u2500 example_config.json # Example configuration\n\u251c\u2500\u2500 pyproject.toml\n\u2514\u2500\u2500 README.md\n```\n\n### Running in Development\n\n```bash\n# Install in editable mode\nuv pip install -e .\n\n# Run the CLI\nmcpsh --help\n\n# Test with example server\npython example_server.py # In one terminal\nmcpsh tools example --config example_config.json # In another\n```\n\n## Related Projects\n\n- [FastMCP](https://gofastmcp.com) - The framework used to build this CLI\n- [Model Context Protocol](https://modelcontextprotocol.io/) - Official MCP specification\n- [Claude Desktop](https://claude.ai/download) - Uses the same configuration format\n\n## License\n\nMIT\n\n## Contributing\n\nContributions welcome! This is a simple tool focused on making MCP server interaction easy from the command line.\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "A clean CLI for interacting with MCP servers using FastMCP",
"version": "0.1.3",
"project_urls": {
"Homepage": "https://github.com/fkesheh/mcpsh",
"Issues": "https://github.com/fkesheh/mcpsh/issues",
"Repository": "https://github.com/fkesheh/mcpsh"
},
"split_keywords": [
"mcp",
" model-context-protocol",
" cli",
" fastmcp",
" tools"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "de041bb6fd77c913cc15e83ee125206c71df59f26ab69027e3a6ed7a1381f9cc",
"md5": "f8b53c90f33419851be5348d22e212cc",
"sha256": "67250fe934078368a198f2a0f38695c414eb185309ca77d8362799b3d049bc10"
},
"downloads": -1,
"filename": "mcpsh-0.1.3-py3-none-any.whl",
"has_sig": false,
"md5_digest": "f8b53c90f33419851be5348d22e212cc",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.10",
"size": 16413,
"upload_time": "2025-10-22T14:39:40",
"upload_time_iso_8601": "2025-10-22T14:39:40.715311Z",
"url": "https://files.pythonhosted.org/packages/de/04/1bb6fd77c913cc15e83ee125206c71df59f26ab69027e3a6ed7a1381f9cc/mcpsh-0.1.3-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "2edb493bf9f8a69daac1831104721029eb493787ee70c628e258fde9aace8bcc",
"md5": "af598e35cbc7629b70f74fbca639680e",
"sha256": "0410e936df7887babcae2408df97a539d99805ab68a87a130b8421130cea7eb0"
},
"downloads": -1,
"filename": "mcpsh-0.1.3.tar.gz",
"has_sig": false,
"md5_digest": "af598e35cbc7629b70f74fbca639680e",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.10",
"size": 15151,
"upload_time": "2025-10-22T14:39:41",
"upload_time_iso_8601": "2025-10-22T14:39:41.940416Z",
"url": "https://files.pythonhosted.org/packages/2e/db/493bf9f8a69daac1831104721029eb493787ee70c628e258fde9aace8bcc/mcpsh-0.1.3.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-10-22 14:39:41",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "fkesheh",
"github_project": "mcpsh",
"travis_ci": false,
"coveralls": false,
"github_actions": false,
"lcname": "mcpsh"
}
JSON
