BlackArch Security Tools MCP Server
A comprehensive Model Context Protocol (MCP) server that integrates BlackArch Linux security tools for educational penetration testing. Built with security-first principles and strict input validation.
What is MCP?
The Model Context Protocol (MCP) is a standard for connecting AI assistants to external data sources and tools. This project serves as a starting point for building your own MCP servers.
Features
- Echo Tool: A simple tool that echoes back any message you send
- Echo Resource: A resource that can be read with custom messages
- FastMCP Framework: Built using the modern FastMCP library
- Comprehensive Testing: Includes PowerShell and Bash test scripts
- Easy Setup: Minimal dependencies and clear structure
Quick Start
Prerequisites
- Python 3.13 or higher
- jq (for JSON formatting in tests)
Installation
- Clone or download this project
- Install dependencies:
or using uv (recommended):pip install -r requirements.txtuv sync
Running the Server
python echo_server.py
The server runs in stdio mode, waiting for JSON-RPC requests.
Testing the Server
Quick Test with jq
# Test tool listing
echo '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-06-18","capabilities":{},"clientInfo":{"name":"test-client","version":"1.0.0"}}}' | python echo_server.py
echo '{"jsonrpc":"2.0","method":"notifications/initialized","params":{}}' | python echo_server.py
echo '{"jsonrpc":"2.0","id":2,"method":"tools/list","params":{}}' | python echo_server.py | jq
Comprehensive Testing
PowerShell (Windows):
& "C:\Program Files\PowerShell\7-preview\pwsh.exe" -File test_echo_mcp.ps1
Bash (Linux/macOS):
chmod +x test_echo_mcp.sh
./test_echo_mcp.sh
Project Structure
project-011/
├── echo_server.py # Main MCP server implementation
├── test_echo_mcp.ps1 # Comprehensive PowerShell test script
├── test_echo_mcp.sh # Bash test script
├── requirements.txt # Python dependencies
├── pyproject.toml # Project configuration
└── README.md # This file
Understanding the Code
Basic MCP Server Structure
from mcp.server.fastmcp import FastMCP
# Create the MCP server
mcp = FastMCP("YourServerName")
# Define a tool
@mcp.tool()
def your_tool(param: str) -> str:
"""Description of what your tool does"""
return f"Result: {param}"
# Define a resource
@mcp.resource("your://{param}")
def your_resource(param: str) -> str:
"""Description of your resource"""
return f"Resource content: {param}"
# Run the server
if __name__ == "__main__":
mcp.run(transport='stdio')
Key Concepts
- Tools: Functions that can be called by AI assistants to perform actions
- Resources: Data sources that can be read by AI assistants
- Transport: How the server communicates (stdio, HTTP, etc.)
- JSON-RPC: The protocol used for communication
Creating Your Own MCP Server
1. Start with the Echo Server
Copy this project and modify echo_server.py:
from mcp.server.fastmcp import FastMCP
mcp = FastMCP("MyCustomServer")
@mcp.tool()
def my_custom_tool(input_data: str) -> str:
"""My custom tool that does something useful"""
# Your logic here
return f"Processed: {input_data}"
if __name__ == "__main__":
mcp.run(transport='stdio')
2. Add More Complex Tools
from typing import List, Dict, Any
import requests
@mcp.tool()
def fetch_weather(city: str) -> Dict[str, Any]:
"""Fetch weather data for a city"""
# Your API call logic here
return {"city": city, "temperature": "22°C", "condition": "sunny"}
@mcp.tool()
def process_data(data: List[str]) -> List[str]:
"""Process a list of data items"""
return [item.upper() for item in data]
3. Add Resources
@mcp.resource("data://{dataset}")
def get_dataset(dataset: str) -> str:
"""Get data from a specific dataset"""
# Your data retrieval logic here
return f"Data from {dataset}: ..."
4. Update Dependencies
Add any new dependencies to requirements.txt:
mcp[cli]>=1.15.0
requests>=2.31.0
pandas>=2.0.0
Integration with AI Assistants
Claude Desktop
Add to your claude_desktop_config.json:
{
"mcpServers": {
"echo-server": {
"command": "python",
"args": ["C:/path/to/your/echo_server.py"]
}
}
}
Other MCP Clients
The server follows the MCP specification and should work with any MCP-compatible client.
Testing Your Server
Manual Testing
-
Initialize the server:
{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-06-18","capabilities":{},"clientInfo":{"name":"test-client","version":"1.0.0"}}} -
Send initialized notification:
{"jsonrpc":"2.0","method":"notifications/initialized","params":{}} -
List available tools:
{"jsonrpc":"2.0","id":2,"method":"tools/list","params":{}} -
Call a tool:
{"jsonrpc":"2.0","id":3,"method":"tools/call","params":{"name":"echo_tool","arguments":{"message":"Hello!"}}}
Automated Testing
Use the provided test scripts as templates for your own testing:
test_echo_mcp.ps1- Comprehensive PowerShell testingtest_echo_mcp.sh- Bash testing
Common Issues and Solutions
"Failed to validate request: Received request before initialization was complete"
Solution: Always send the initialization sequence first:
initializerequestnotifications/initialized- Then your actual requests
"Tool not found" errors
Solution: Check that your tool is properly decorated with @mcp.tool() and the name matches exactly.
Performance issues
Solution:
- Use async functions for I/O operations
- Implement proper error handling
- Consider caching for expensive operations
Next Steps
- Explore the MCP Specification: Official MCP Documentation
- Check out FastMCP: FastMCP GitHub
- Build Real Tools: Create tools that interact with APIs, databases, or file systems
- Add Authentication: Implement security for production use
- Deploy: Consider containerization with Docker
Contributing
This is a template project. Feel free to:
- Fork and modify for your needs
- Add more examples
- Improve the test scripts
- Share your MCP server implementations
License
This project is provided as-is for educational and development purposes.
Happy MCP Development! 🚀
For questions or issues, refer to the MCP Community or create an issue in your fork of this project.