mcpsh (Fkesheh)

mcpsh

一个渐进式CLI和Python API，用于使用FastMCP与模型上下文协议（MCP）服务器交互。

将任何MCP服务器转换为CLI工具 -非常适合AI代理、自动化脚本和手动操作。通过命令行的简单性和通用性，获得丰富的MCP工具生态系统。

特性

• 🎯 渐进式界面 -自然、直观的命令流，引导您完成发现
• 🐍 Python API -直接在Python脚本中导入以进行编程访问
• 🚀 简单快捷 -内置FastMCP，可实现可靠的MCP通信
• ⚡ 零安装 -跑步 uvx mcpsh 无需安装
• 📋 列表和发现 -从任何MCP服务器探索工具、资源和提示
• 🔍 架构检查 -查看详细的工具模式和参数要求
• 🔧 执行工具 -直接从命令行调用MCP工具
• 📖 阅读资源 -使用格式化输出访问资源数据
• 🎯 清洁输出 -默认情况下，服务器日志被抑制，以获得干净、可解析的输出
• 📝 灵活的格式 -以JSON或Markdown格式输出结果
• ⚙️ 基于配置 -使用标准MCP配置格式（与Claude Desktop兼容）

为什么选择MCP的CLI？

🤖 非常适合AI代理自动化

虽然MCP（模型上下文协议）功能强大，但通过CLI公开MCP服务器为AI/LLM代理提供了关键优势：

减少上下文开销

• MCP需要嵌入 每个工具的模式 进入LLM的上下文窗口
• 随着添加更多MCP工具，上下文膨胀，模型性能下降
• CLI调用是精简的——只有命令名和简单的参数
• 结果：您的AI代理可以访问更多工具，而不会达到上下文限制

通用LLM支持

• 任何可以执行shell命令的LLM 可以使用这些工具
• 与Claude、GPT-4、本地模型、Cursor、Aider和定制代理合作
• 无需MCP特定的集成或协议支持
• 结果：在所有AI编码助手中使用相同的工具

更简单、更可靠的函数调用

• LLM生成CLI命令比复杂的协议调用更可靠
• 熟悉的bash语法可以减少幻觉和错误
• 标准输入/输出使调试变得简单
• 结果：更高的成功率和更少的代理失败

在克劳德技能和技能mcp中使用

Claude Skills允许您上传Claude可以执行的代码。然而， 技能mcp 提供了一种使用MCP的优越方法：

• ✅ 未锁定到克劳德 -在Claude、Cursor和任何MCP客户端中的技能工作
• ✅ 无需手动上传 -通过MCP以编程方式管理技能
• ✅ 更好的工具访问 -使用 mcpsh 您访问数据库、API、监控工具等的技能。
• ✅ 通用且面向未来 -MCP协议与专有Claude功能

使用mcpsh CLI的示例技能：

# In a skill-mcp skill script
import subprocess
import json

# Query database using mcpsh progressive CLI
result = subprocess.run([
    "mcpsh", "postgres", "query",
    "--args", '{"sql": "SELECT * FROM users WHERE active = true"}',
    "-f", "json"
], capture_output=True, text=True)

data = json.loads(result.stdout)  # Pure JSON output - no need to skip lines!
# Process data...

甚至更好-使用Python API：

# In a skill-mcp skill script
from mcpsh import call_tool

# Query database - much cleaner!
data = call_tool("postgres", "query",
    {"sql": "SELECT * FROM users WHERE active = true"},
    parse_json=True)
# Process data...

更多AI代理示例：

# AI coding assistant queries your database
mcpsh postgres query --args '{"sql": "SELECT * FROM users WHERE active = true"}'

# AI ops agent checks production metrics
mcpsh 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 databricks list_clusters --args '{}'
mcpsh skill-mcp run_skill_script --args '{"skill_name": "deploy", "script_path": "deploy.py"}'

🌉 世界之间的桥梁

得到 两者中最好的:

• 访问MCP服务器的丰富生态系统（数据库、API、监控等）
• 使用CLI工具的简单性和通用性
• 非常适合 技能mcp 技能-将MCP工具访问与技能执行相结合
• 无需选择-MCP服务器成为CLI工具！

快速开始

安装

# Option 1: Run directly with uvx (no installation required)
uvx mcpsh
uvx mcpsh   --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 .

设置配置

选项1：使用现有的Claude桌面配置

如果您已经安装并配置了Claude Desktop，CLI将自动使用它：

mcpsh

选项2：创建自定义配置

创建一个 ~/.mcpsh/mcp_config.json 主目录中的文件：

# Create the directory
mkdir -p ~/.mcpsh

# Create the config file
cat > ~/.mcpsh/mcp_config.json  [--config PATH] [-f FORMAT] [--resources] [--prompts]

列出服务器上的所有可用工具。

选项：

• --resources -列出资源而不是工具
• --prompts -列出提示而不是工具

示例：

# List tools from a server
mcpsh postgres

# List tools in JSON format
mcpsh postgres -f json

# List resources instead
mcpsh postgres --resources

# List prompts
mcpsh postgres --prompts

两个参数-显示工具信息或执行

mcpsh   [--args JSON] [--config PATH] [-f FORMAT]

没有 --args：显示详细的工具信息，包括参数和示例用法。

随着 --args：使用提供的参数执行工具。

示例：

# Get detailed info about a tool
mcpsh postgres query

# Execute tool with arguments
mcpsh postgres query --args '{"sql": "SELECT * FROM users LIMIT 5"}'

# Execute with JSON output (perfect for scripting)
mcpsh postgres query --args '{"sql": "SELECT * FROM users"}' -f json

# Complex nested arguments
mcpsh new-relic run_nrql_query --args '{
  "query_input": {
    "nrql": "SELECT count(*) FROM Transaction SINCE 1 hour ago"
  }
}'

所有级别都有特殊标志

常见选项：

• --config, -c -MCP配置文件的路径
• --format, -f -输出格式： markdown （默认）或 json
• --help, -h -显示帮助消息

示例：

# Get help at any level
mcpsh -h
mcpsh postgres -h
mcpsh postgres query -h

# Use JSON format at any level
mcpsh -f json
mcpsh postgres -f json
mcpsh postgres query --args '{"sql": "SELECT 1"}' -f json

资源操作

使用特殊标志访问资源：

CLI：

# List resources from a server
mcpsh  --resources

# Read a specific resource
mcpsh  --read 

# List prompts from a server
mcpsh  --prompts

示例：

# List all resources
mcpsh skill-mcp --resources

# Read specific resource
mcpsh skill-mcp --read "skill://data-analysis/SKILL.md"

# List prompts
mcpsh skill-mcp --prompts

# Works with -f json too
mcpsh skill-mcp --resources -f json

Python API：

from mcpsh import MCPClient, list_resources, read_resource

# Use convenience functions
resources = list_resources("skill-mcp")
content = read_resource("skill-mcp", "skill://data-analysis/SKILL.md")

# Or use MCPClient
with MCPClient("skill-mcp") as client:
    resources = client.list_resources()
    content = client.read_resource("skill://data-analysis/SKILL.md")
    prompts = client.list_prompts()

用法示例

发现工具模式

渐进式界面指导您完成工具发现：

# 1. See what tools are available
mcpsh new-relic

# 2. Get detailed info about a specific tool
mcpsh new-relic run_nrql_query

# This shows:
# - Tool description
# - Parameter details (required/optional, types, descriptions)
# - Nested parameter structures
# - Example usage command

# 3. Copy the example and modify it
mcpsh new-relic run_nrql_query --args '{
  "query_input": {
    "nrql": "SELECT count(*) FROM Transaction SINCE 1 hour ago"
  }
}'

数据库操作

# List database tools
mcpsh postgres

# List database tables
mcpsh postgres list_tables --args '{}'

# Get table structure
mcpsh postgres describe_table --args '{"table": "users"}'

# Run a query
mcpsh postgres query --args '{
  "sql": "SELECT name, email FROM users WHERE active = true ORDER BY created_at DESC LIMIT 5"
}'

# Count records
mcpsh postgres query --args '{
  "sql": "SELECT COUNT(*) as total FROM orders WHERE status = '\''completed'\''"
}'

技能管理与技能mcp

技能mcp 是一个MCP服务器，允许您以编程方式创建、管理和执行技能。它优于Claude Skills，因为它：

• ✅ 适用于Claude、Cursor和任何MCP客户端（未锁定到Claude）
• ✅ 无需手动上传文件-通过MCP协议管理技能
• ✅ 技能可以使用 mcpsh 访问任何MCP服务器（数据库、API等）
• ✅ 本地优先、面向未来、开放标准

管理技能：

# List available skill tools
mcpsh skill-mcp

# Read skill documentation
mcpsh skill-mcp --read-uri "skill://data-analysis/SKILL.md"

# Get skill details
mcpsh skill-mcp get_skill_details --args '{"skill_name": "data-processor"}'

# Execute a skill script
mcpsh skill-mcp run_skill_script --args '{
  "skill_name": "data-processor",
  "script_path": "scripts/process.py",
  "args": ["--input", "data/input.csv", "--output", "data/output.json"]
}'

使用mcpsh内部技能（CLI方法）：

技能可以使用 mcpsh CLI访问任何MCP服务器：

# 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", server, tool,
        "--args", json.dumps(args),
        "-f", "json"
    ], capture_output=True, text=True)

    # Pure JSON output - no need to skip lines!
    return json.loads(result.stdout)

# Query database
users = run_mcpsh("postgres", "query", {
    "sql": "SELECT COUNT(*) as count FROM users WHERE last_login  100:
    print(f"Alert: {users['count']} inactive users found")

使用mcpsh Python API内部技能（推荐）：

甚至更好-直接使用Python API：

# Example: skill that queries database and sends alerts
# ~/.skill-mcp/skills/db-monitor/scripts/check_health.py

from mcpsh import call_tool

# Query database - much simpler!
users = call_tool("postgres", "query", {
    "sql": "SELECT COUNT(*) as count FROM users WHERE last_login  100:
    print(f"Alert: {users['results'][0]['count']} inactive users found")

这种方法使您的技能能够获得：

• 数据库（PostgreSQL、MySQL等）
• 监控工具（New Relic、Datadog等）
• 云平台（Rancher、AWS等）
• 配置中的任何MCP服务器！

API勘探

# List API explorer capabilities
mcpsh api-explorer

# Make a GET request
mcpsh api-explorer make_request --args '{
  "url": "https://jsonplaceholder.typicode.com/posts/1",
  "method": "GET"
}'

# Make a POST request
mcpsh api-explorer make_request --args '{
  "url": "https://api.example.com/data",
  "method": "POST",
  "body": {"title": "New Item", "completed": false},
  "headers": {"Content-Type": "application/json"}
}'

使用New Relic进行监控

# List available monitoring tools
mcpsh new-relic

# Query application metrics
mcpsh new-relic query_nrql --args '{
  "query": "SELECT average(duration) FROM Transaction WHERE appName = '\''MyApp'\'' SINCE 1 hour ago"
}'

# Get service health
mcpsh new-relic get_service_health --args '{
  "service_name": "api-gateway"
}'

脚本和自动化

在Bash脚本中使用CLI：

# Pure JSON output - perfect for scripting (use -f json)
mcpsh new-relic run_nrql_query \
  --args '{"query_input":{"nrql":"SELECT count(*) FROM Transaction SINCE 1 hour ago"}}' \
  -f json

# Parse JSON output with jq - pure JSON, no need to skip lines!
RESULT=$(mcpsh new-relic run_nrql_query \
  --args '{"query_input":{"nrql":"SELECT count(*) FROM Transaction SINCE 1 hour ago"}}' \
  -f json)

echo "$RESULT" | jq -r '.results[0].count'

# Use in a bash script
#!/bin/bash
TRANSACTION_COUNT=$(mcpsh new-relic run_nrql_query \
  --args '{"query_input":{"nrql":"SELECT count(*) FROM Transaction SINCE 1 hour ago"}}' \
  -f json | jq -r '.results[0].count')

echo "Total transactions: $TRANSACTION_COUNT"

# Error handling in scripts
if OUTPUT=$(mcpsh postgres query \
  --args '{"sql": "SELECT COUNT(*) FROM users"}'); then
  echo "Success: $OUTPUT"
else
  echo "Failed to query database"
  exit 1
fi

在脚本中使用Python API（推荐）：

#!/usr/bin/env python3
from mcpsh import call_tool, MCPClient

# Simple one-off calls
result = call_tool("postgres", "query", {"sql": "SELECT COUNT(*) FROM users"}, parse_json=True)
print(f"Total users: {result}")

# Multiple calls with context manager (reuses connection)
with MCPClient("new-relic") as client:
    # Check transaction count
    transactions = client.call_tool("run_nrql_query", {
        "query_input": {"nrql": "SELECT count(*) FROM Transaction SINCE 1 hour ago"}
    }, parse_json=True)

    # Check error rate
    errors = client.call_tool("run_nrql_query", {
        "query_input": {"nrql": "SELECT count(*) FROM TransactionError SINCE 1 hour ago"}
    }, parse_json=True)

    print(f"Transactions: {transactions['results'][0]['count']}")
    print(f"Errors: {errors['results'][0]['count']}")

脚本编写技巧：

• 使用 -f json 用于纯JSON输出（无额外消息）
• JSON输出可以直接通过管道传输到 jq 或解析为 json.loads() -无需预处理！
• Markdown格式（默认）包括成功消息和人类可读性格式
• 管道至 jq 用于JSON解析和提取
• 检查退出代码以进行错误处理
• 使用 --verbose 仅在调试问题时标记

高级用法

自定义配置文件

# Development configuration
mcpsh --config ./config/dev.json

# Production configuration
mcpsh --config ./config/prod.json

# Testing with example server
mcpsh example --config ./example_config.json

管道和自动化

# Save tool output to file
mcpsh postgres query --args '{"sql": "SELECT * FROM users"}' > users.txt

# Use in scripts
#!/bin/bash
TABLES=$(mcpsh postgres list_tables --args '{}')
echo "Database has these tables: $TABLES"

# Process with other tools (use -f json for clean output)
mcpsh postgres query --args '{"sql": "SELECT * FROM metrics"}' -f json | jq '.[] | select(.value > 100)'

使用不同的服务器类型

# Local Python servers
mcpsh example --config example_config.json

# Remote HTTP servers (configure with "url" and "transport": "http")
mcpsh remote-api

# NPX/UVX servers (configure with "command": "uvx" or "npx")
mcpsh mcp-package-server

示例服务器

该存储库包括一个用于测试的示例MCP服务器：

运行示例

# In one terminal, start the example server:
python example_server.py

# In another terminal, use the progressive CLI:
mcpsh example --config example_config.json
mcpsh example greet --args '{"name": "World"}'
mcpsh example add --args '{"a": 5, "b": 3}'
mcpsh example --resources --config example_config.json
mcpsh example --read "data://example/apple" --config example_config.json
mcpsh example --prompts --config example_config.json

示例服务器提供：

• 工具: greet, add, multiply
• 资源: data://example/info, data://example/{item} （模板）
• 提示词: analyze_data

故障排除

“找不到服务器”

确保服务器名称与配置中的名称完全匹配：

# List servers to see exact names
mcpsh

“找不到工具”

列出工具以查看确切名称（一些服务器添加前缀）：

mcpsh 

# Note: Multi-server configs may prefix tool names
# Example: "servername_toolname"

“JSON无效”

确保你的参数是正确引用的有效JSON：

# ✓ Good - single quotes outside, double quotes inside
mcpsh server tool --args '{"key": "value"}'

# ✗ Bad - missing quotes
mcpsh server tool --args '{key: value}'

连接问题

# Test server connectivity by listing tools
mcpsh 

# This will show if the server is responding and any errors

提示和最佳实践

1. 遵循渐进式模式：从以下内容开始 mcpsh，然后添加服务器，然后添加工具，然后添加参数
2. 使用 -h 寻求任何级别的帮助：在构建命令时获取上下文帮助
3. 执行前检查工具信息：运行 mcpsh 查看参数和示例
4. 使用有效的JSON作为参数：JSON周围有单引号，里面有双引号
5. 使用 -f json 用于脚本编写：获得纯JSON输出，非常适合管道和解析
6. 尝试Python API：更简洁的代码，更好的错误处理，连接重用
7. 使用示例服务器进行测试：使用 example_config.json 验证CLI是否正常工作
8. 使用自定义配置：针对不同环境（开发、暂存、生产）的单独配置

渐进式指挥参考

CLI使用渐进式界面，其中命令相互构建：

特殊旗帜（可在任何级别使用）：

常见模式

勘探模式

# 1. See what servers are available
mcpsh

# 2. Check what a server offers
mcpsh postgres

# 3. Look at specific capabilities
mcpsh postgres --resources
mcpsh postgres --prompts

# 4. Get tool details
mcpsh postgres query

# 5. Try it out
mcpsh postgres query --args '{"sql": "SELECT 1"}'

集成模式（CLI）

# Use MCP CLI in larger workflows
#!/bin/bash

# Get data from MCP server
DATA=$(mcpsh postgres query --args '{"sql": "SELECT * FROM metrics"}' -f json)

# Process with other tools
echo "$DATA" | jq '.[] | select(.value > 100)'

# Store results
mcpsh postgres query --args '{"sql": "..."}' > output.json

集成模式（Python API）

#!/usr/bin/env python3
from mcpsh import MCPClient

# Reuse connection for multiple operations
with MCPClient("postgres") as client:
    # Get data
    metrics = client.call_tool("query",
        {"sql": "SELECT * FROM metrics"},
        parse_json=True)

    # Process with Python
    high_values = [m for m in metrics if m['value'] > 100]

    # Store results
    import json
    with open('output.json', 'w') as f:
        json.dump(high_values, f)

获取帮助

渐进式界面支持各个级别的帮助：

# General help
mcpsh --help
mcpsh -h

# Server-level help
mcpsh postgres --help
mcpsh postgres -h

# Tool-level help
mcpsh postgres query --help
mcpsh postgres query -h

Python API参考

导入mcpsh以进行编程访问：

from mcpsh import (
    MCPClient,      # Main client class
    list_servers,   # List configured servers
    list_tools,     # List tools from a server
    call_tool,      # Execute a tool
    list_resources, # List resources
    read_resource,  # Read a resource
)

# All functions support both sync and async
# Use MCPClient for connection reuse across multiple calls

需求

• Python 3.10+
• FastMCP 2.12.5+
• 点击8.0.0+
• 丰富14.2.0+

发展

项目结构

mcpsh/
├── src/
│   └── mcpsh/
│       ├── __init__.py    # Package exports (Python API)
│       ├── main.py        # Progressive CLI implementation
│       ├── client.py      # Python API for importing
│       └── config.py      # Configuration loader
├── tests/
│   ├── test_main.py       # CLI tests
│   └── test_client.py     # Python API tests
├── example_server.py      # Example MCP server for testing
├── example_config.json    # Example configuration
├── pyproject.toml
└── README.md

在发展中奔跑

# Install in editable mode
uv pip install -e .

# Run tests
uv run pytest

# Run the CLI
mcpsh --help
mcpsh

# Test with example server
python example_server.py  # In one terminal
mcpsh example --config example_config.json  # In another

相关项目

• FastMCP -用于构建此CLI的框架
• 模型上下文协议 -MCP官方规范
• 克劳德桌面 -使用相同的配置格式

许可证

麻省理工学院

贡献

欢迎投稿！这是一个简单的工具，专注于从命令行使MCP服务器交互变得容易。