🐚 Bash 中的 MCP 服务器

一个轻量级、零开销的 Model Context Protocol (MCP) 服务器实现，完全用纯 Bash 编写。

为什么？ 大多数 MCP 服务器只是带有模式转换的 API 封装。而这个实现提供了一种无需 Node.js、Python 或其他重型运行时的零开销替代方案。

---

📋 特性

• ✅ 通过标准输入输出支持完整的 JSON-RPC 2.0 协议
• ✅ 完整的 MCP 协议实现
• ✅ 通过函数命名约定动态发现工具
• ✅ 通过 JSON 文件进行外部配置
• ✅ 易于扩展自定义工具

---

🔧 需求

• Bash shell
• jq 用于 JSON 处理（在 macOS 上可使用 brew install jq）

---

🚀 快速开始

1. 克隆仓库

git clone https://github.com/muthuishere/mcp-server-bash-sdk
cd mcp-server-bash-sdk

2. 使脚本可执行

chmod +x mcpserver_core.sh moviemcpserver.sh

3. 试用

echo '{"jsonrpc": "2.0", "method": "tools/call", "params": {"name": "get_movies"}, "id": 1}' | ./moviemcpserver.sh

---

🏗️ 架构

┌─────────────┐         ┌────────────────────────┐
│ MCP 主机    │         │ MCP 服务器             │
│ (AI 系统)   │◄──────► │ (moviemcpserver.sh)    │
└─────────────┘ stdio   └────────────────────────┘
                             │
                     ┌───────┴──────────┐
                     ▼                  ▼
            ┌───────────────────┐  ┌───────────────┐
            │ 协议层          │  │ 业务逻辑      │
            │(mcpserver_core.sh)│  │(tool_* 函数) │
            └───────────────────┘  └───────────────┘
                     │                  │
                     ▼                  ▼
              ┌─────────────────┐  ┌───────────────┐
              │ 配置文件        │  │ 外部服务/APIs │
              │ (JSON 文件)     │  │               │
              └─────────────────┘  └───────────────┘

• mcpserver_core.sh: 处理 JSON-RPC 和 MCP 协议
• moviemcpserver.sh: 包含业务逻辑函数
• assets/: JSON 配置文件

---

🔌 创建您自己的 MCP 服务器

工具函数指南

在为 MCP 服务器实现工具函数时，请遵循以下指南：

1. 命名约定：所有工具函数必须以 tool_ 开头，后跟 tools_list.json 中定义的相同名称。
2. 参数：每个函数应接受一个名为 $1 的单个参数，其中包含 JSON 格式的参数。
3. 成功模式：对于成功操作，输出结果并返回 0。
4. 错误模式：对于验证错误，输出错误信息并返回 1。
5. 自动发现：所有工具函数都会根据 tools_list.json 自动暴露给 MCP 服务器。

实现步骤

1. 创建您的业务逻辑文件（例如 weatherserver.sh）

#!/bin/bash
# 天气 API 实现

# 在加载核心之前覆盖配置路径
MCP_CONFIG_FILE="$(dirname "${BASH_SOURCE[0]}")/assets/weatherserver_config.json"
MCP_TOOLS_LIST_FILE="$(dirname "${BASH_SOURCE[0]}")/assets/weatherserver_tools.json"
MCP_LOG_FILE="$(dirname "${BASH_SOURCE[0]}")/logs/weatherserver.log"

# MCP 服务器工具函数指南：
# 1. 所有工具函数都应以“tool_”开头，后跟 tools_list.json 中定义的相同名称。
# 2. 函数应接受一个名为“$1”的单个参数，该参数包含 JSON 格式的参数。
# 3. 对于成功操作：输出预期结果并返回 0。
# 4. 对于错误：输出错误信息并返回 1。
# 5. 所有工具函数都会根据 tools_list.json 自动暴露给 MCP 服务器。

# 加载核心 MCP 服务器实现
source "$(dirname "${BASH_SOURCE[0]}")/mcpserver_core.sh"

# 访问环境变量
API_KEY="${MCP_API_KEY:-default_key}"

# 工具：获取某个地点的当前天气
# 参数：接收包含地点信息的 JSON 对象
# 成功：输出 JSON 格式的结果并返回 0
# 错误：输出错误信息并返回 1
tool_get_weather() {
  local args="$1"
  local location=$(echo "$args" | jq -r '.location')
  
  # 参数验证
  if [[ -z "$location" ]]; then
    echo "缺少必需参数：location"
    return 1
  fi
  
  # 调用外部 API
  local weather=$(curl -s "https://api.example.com/weather?location=$location&apikey=$API_KEY")
  echo "$weather"
  return 0
}


# 启动 MCP 服务器
run_mcp_server "$@"

2. 创建 assets/weatherserver_tools.json

{
  "tools": [
    {
      "name": "get_weather",
      "description": "获取某个地点的当前天气",
      "inputSchema": {
        "type": "object",
        "properties": {
          "location": {
            "type": "string",
            "description": "城市名称或坐标"
          }
        },
        "required": ["location"]
      }
    }
  ]
}

3. 创建 assets/weatherserver_config.json

{
  "protocolVersion": "2025-03-26",
  "serverInfo": {
    "name": "WeatherServer",
    "version": "1.0.0"
  },
  "capabilities": {
    "tools": {
      "listChanged": true
    }
  },
  "instructions": "此服务器提供天气信息。"
}

4. 使您的文件可执行

chmod +x weatherserver.sh

---

🖥️ 与 VS Code 和 GitHub Copilot 配合使用

1. 更新 VS Code 的 settings.json

"mcp": {
    "servers": {
        "my-weather-server": {
            "type": "stdio",
            "command": "/path/to/your/weatherserver.sh",
            "args": [],
            "env": {
                "MCP_API_KEY": "your-api-key"
            }
        }
    }
}

2. 与 GitHub Copilot Chat 配合使用

/mcp my-weather-server 获取纽约的天气

---

🚫 局限性

• 不支持并发/并行处理
• 内存管理有限
• 不支持流式响应
• 并非为高吞吐量设计

但对于 AI 助手和本地工具执行来说，这些并不是主要问题。

---

📄 许可证

本项目采用 MIT 许可证授权——详情请参阅 LICENSE 文件。

博客：https://medium.com/@muthuishere/why-i-built-an-mcp-server-sdk-in-shell-yes-bash-6f2192072279

mcp-server-bash-sdk 快速上手指南

mcp-server-bash-sdk 是一个纯 Bash 实现的轻量级、零开销 Model Context Protocol (MCP) 服务器。它无需 Node.js 或 Python 等重型运行时，非常适合在本地快速构建 AI 工具接口。

环境准备

在开始之前，请确保您的系统满足以下要求：

• 操作系统：Linux 或 macOS（需具备 Bash Shell 环境）
• 核心依赖：
  • bash：大多数系统默认安装。
  • jq：用于 JSON 数据处理。
    • macOS: brew install jq
    • Ubuntu/Debian: sudo apt-get install jq
    • CentOS/RHEL: sudo yum install jq

安装步骤

1. 克隆仓库 将项目代码下载到本地：

   git clone https://github.com/muthuishere/mcp-server-bash-sdk
   cd mcp-server-bash-sdk
   

2. 赋予执行权限 使核心脚本和示例服务器脚本可执行：

   chmod +x mcpserver_core.sh moviemcpserver.sh
   

基本使用

安装完成后，您可以直接通过标准输入（stdio）向服务器发送 JSON-RPC 请求进行测试。以下示例调用内置的 get_movies 工具：

echo '{"jsonrpc": "2.0", "method": "tools/call", "params": {"name": "get_movies"}, "id": 1}' | ./moviemcpserver.sh

执行后，终端将返回符合 MCP 协议的 JSON 响应结果。

---

💡 进阶提示：集成 VS Code & GitHub Copilot

若要在 VS Code 中使用该服务，请在 settings.json 中添加如下配置（以自定义天气服务为例）：

"mcp": {
    "servers": {
        "my-weather-server": {
            "type": "stdio",
            "command": "/path/to/your/weatherserver.sh",
            "args": [],
            "env": {
                "MCP_API_KEY": "your-api-key"
            }
        }
    }
}

配置生效后，即可在 GitHub Copilot Chat 中通过 /mcp 命令调用您的 Bash 工具。