https://github.com/deemkeen/shell-mcp
serve your MCP tools with the power of bash!
https://github.com/deemkeen/shell-mcp
bash cli mcp
Last synced: 3 months ago
JSON representation
serve your MCP tools with the power of bash!
- Host: GitHub
- URL: https://github.com/deemkeen/shell-mcp
- Owner: deemkeen
- Created: 2025-04-10T21:56:26.000Z (about 1 year ago)
- Default Branch: master
- Last Pushed: 2025-04-28T20:30:47.000Z (about 1 year ago)
- Last Synced: 2025-04-28T21:30:46.598Z (about 1 year ago)
- Topics: bash, cli, mcp
- Language: Shell
- Homepage:
- Size: 8.79 KB
- Stars: 2
- Watchers: 1
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
Awesome Lists containing this project
README
# Shell MCP (Model Control Protocol)
A lightweight Bash implementation of an MCP server that allows creating and using custom command-line tools via a JSON-RPC interface.
## Overview
Shell MCP provides a simple framework to create, manage, and use custom command-line tools. The server loads tools from the `tools` directory and makes them available through a standardized interface.
## Getting Started
### Running the Server
To start the MCP server with the default configuration:
```bash
./mcp-server.sh
```
The server will load all tools from the `tools` directory and begin listening for commands via stdin.
## Adding New Tools
Shell MCP includes a CLI option to easily create new tools.
### Command Line Options
```bash
# Create a new tool
./mcp-server.sh --add-tool NAME DESCRIPTION "PARAM1:TYPE,PARAM2:TYPE"
# Show help information
./mcp-server.sh --help
```
### Example: Creating a New Tool
```bash
# Create a new multiplication tool
./mcp-server.sh --add-tool multiply "Multiplies two numbers" "num1:int,num2:int"
```
This will generate a new tool file at `tools/multiply.tool.sh` with a basic implementation template.
### Contributing Your Own Tools
We welcome contributions from the community! You can create your own general-purpose tools and submit them as pull requests.
Guidelines for contributing tools:
1. Tools should be general-purpose and useful to a wide audience
2. Follow the existing pattern for tool implementation
3. Include clear documentation within your tool file
4. Make sure your tool works correctly before submitting
5. Submit a pull request with your tool added to the `tools` directory
### Tool Structure
Each tool consists of:
1. A function that implements the tool's logic
2. A call to `register_tool` to make the tool available to the server
Here's an example of a simple tool implementation:
```bash
#!/usr/bin/env bash
# Addition tool implementation
# Function that performs the addition
addition_impl() {
local num1=$1
local num2=$2
# Calculate the sum
local sum=$((num1 + num2))
echo "sum of two numbers is $sum"
}
# Register the tool with the server
register_tool \
"addition" \
"addition of two numbers" \
"num1:int,num2:int" \
"addition_impl"
```
## Important Notes for Tool Development
1. Each tool function should accept parameters in the order they are defined
2. Tools must use a single `echo` statement at the end to return their result
3. Parameter types are for documentation only - all parameters are passed as strings
4. Make the tool file executable with `chmod +x` after creating it manually
## Project Structure
```
shell-mcp/
├── mcp-server.sh # Main server script
├── tools/ # Directory containing all tools
│ ├── addition.tool.sh # Example tool
│ ├── bmi_calculator.tool.sh # Example tool
│ └── pokemon_fetcher.tool.sh # Example tool
└── mcp_server.log # Server log file (created when server runs)
```
## Protocol
The server implements a simplified JSON-RPC interface with the following methods:
- `initialize`: Initializes the server and returns its capabilities
- `tools/list`: Lists all available tools with their descriptions and parameters
- `tools/call`: Calls a specific tool with the provided arguments
- `resources/list`: Lists available resources (not implemented)
- `prompts/list`: Lists available prompts (not implemented)
## Requirements
- Bash 4.0 or higher
- `jq` for JSON processing
## License
This project is open source and available under the MIT License.