🐚 MCP Server in Bash

A lightweight, zero-overhead implementation of the Model Context Protocol (MCP) server in pure Bash.

Why? Most MCP servers are just API wrappers with schema conversion. This implementation provides a zero-overhead alternative to Node.js, Python, or other heavy runtimes.

📋 Features

• ✅ Full JSON-RPC 2.0 protocol over stdio
• ✅ Complete MCP protocol implementation
• ✅ Dynamic tool discovery via function naming convention
• ✅ External configuration via JSON files
• ✅ Easy to extend with custom tools

🔧 Requirements

• Bash shell
• jq for JSON processing (brew install jq on macOS)

🚀 Quick Start

1. Clone the repo

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

1. Make scripts executable

chmod +x mcpserver_core.sh moviemcpserver.sh

1. Try it out

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

🏗️ Architecture

┌─────────────┐         ┌────────────────────────┐
│ MCP Host    │         │ MCP Server             │
│ (AI System) │◄──────► │ (moviemcpserver.sh)    │
└─────────────┘ stdio   └────────────────────────┘
                             │
                     ┌───────┴──────────┐
                     ▼                  ▼
              ┌─────────────────┐  ┌───────────────┐
              │ Protocol Layer  │  │ Business Logic│
              │(mcpserver_core.sh)│  │(tool_* funcs)│
              └─────────────────┘  └───────────────┘
                     │                  │
                     ▼                  ▼
              ┌─────────────────┐  ┌───────────────┐
              │ Configuration   │  │ External      │
              │ (JSON Files)    │  │ Services/APIs │
              └─────────────────┘  └───────────────┘

• mcpserver_core.sh: Handles JSON-RPC and MCP protocol
• moviemcpserver.sh: Contains business logic functions
• assets/: JSON configuration files

🔌 Creating Your Own MCP Server

1. Create your business logic file (e.g., weatherserver.sh)

#!/bin/bash
# Weather API implementation

# Source the core MCP server
source "$(dirname "${BASH_SOURCE[0]}")/mcpserver_core.sh"

# Access environment variables
API_KEY="${MCP_API_KEY:-default_key}"

# Weather tool implementation
tool_get_weather() {
  local args="$1"
  local location=$(echo "$args" | jq -r '.location')
  
  # Call external API
  local weather=$(curl -s "https://api.example.com/weather?location=$location&apikey=$API_KEY")
  echo "$weather"
  return 0
}

# Forecast tool implementation
tool_get_forecast() {
  local args="$1"
  local location=$(echo "$args" | jq -r '.location')
  local days=$(echo "$args" | jq -r '.days')
  
  local forecast=$(curl -s "https://api.example.com/forecast?location=$location&days=$days&apikey=$API_KEY")
  echo "$forecast"
  return 0
}

# Start the MCP server
run_mcp_server "$@"

1. Create tools_list.json in the assets directory

{
  "tools": [
    {
      "name": "get_weather",
      "description": "Get current weather for a location",
      "parameters": {
        "type": "object",
        "properties": {
          "location": {
            "type": "string",
            "description": "City name or coordinates"
          }
        },
        "required": ["location"]
      }
    },
    {
      "name": "get_forecast",
      "description": "Get weather forecast for multiple days",
      "parameters": {
        "type": "object",
        "properties": {
          "location": {
            "type": "string",
            "description": "City name or coordinates"
          },
          "days": {
            "type": "integer",
            "description": "Number of days to forecast"
          }
        },
        "required": ["location", "days"]
      }
    }
  ]
}

1. Update mcpserverconfig.json

{
  "protocolVersion": "0.1.0",
  "serverInfo": {
    "name": "WeatherServer",
    "version": "1.0.0"
  },
  "capabilities": {
    "tools": {
      "listChanged": true
    }
  },
  "instructions": "This server provides weather information and forecasts."
}

1. Make your file executable

chmod +x weatherserver.sh

🖥️ Using with VS Code & GitHub Copilot

1. Update 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"
            }
        }
    }
}

1. Use with GitHub Copilot Chat

/mcp my-weather-server get weather for New York

🚫 Limitations

• No concurrency/parallel processing
• Limited memory management
• No streaming responses
• Not designed for high throughput

For AI assistants and local tool execution, these aren't blocking issues.

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

The complete code is available at: https://github.com/muthuishere/mcp-server-bash-sdk