AdminMCP (ACP)

A comprehensive MCP (Model Context Protocol) based agent environment for system administration and automation tasks. AdminMCP provides both a CLI tool for managing MCP servers and a server implementation with built-in tools and resources for administrative operations.

Table of Contents

• Project Description
• Features
• Installation
• Usage Examples
• Configuration
• Development Setup
• Testing
• Contributing
• License

Project Description

AdminMCP is a dual-purpose tool that serves as both a command-line interface (CLI) for managing MCP servers and an MCP server itself. The project aims to create a robust environment for system administration tasks through MCP-compatible agents.

The CLI component (acp) provides easy management of MCP server processes, while the server component offers a collection of tools and resources for common administrative and computational tasks. Future versions will include client functionality for connecting to and interacting with MCP servers.

Architecture

• CLI Tool: Command-line interface for server lifecycle management
• MCP Server: FastMCP-based server providing tools and resources
• Configuration System: User-configurable settings stored in ~/.config/adminmcp/
• Client (Planned): MCP client for connecting to servers and executing tasks

Features

Current Features

CLI Server Management

• Server Control: Start and stop MCP servers as background processes
• Process Management: Automatic PID tracking and safe process termination
• Safety Checks: Prevents multiple server instances and handles edge cases

MCP Server Tools

• Mathematical Operations: Add, subtract, multiply, divide numbers
• Mathematical Constants: Access to , e, via resource endpoints
• Number Utilities: Check if numbers are even/odd
• DateTime Resources: Current datetime with timezone information
• Wikipedia Integration: Fetch article summaries from Wikipedia

Configuration Management

• Initialization: Automated setup of configuration directories
• User Settings: Customizable server port and logging levels
• MCP Server Registry: Management of connected MCP servers

Planned Features

Client Functionality

• Server Connection: Connect to MCP servers via WebSocket/SSE
• Tool Execution: Remote execution of server-provided tools
• Resource Access: Query server resources programmatically
• Interactive Mode: REPL for interactive server interaction

Advanced Administration Tools

• System Monitoring: CPU, memory, disk usage tools
• File Operations: Safe file manipulation tools
• Network Utilities: DNS lookup, port scanning, connectivity tests
• Process Management: List, start, stop system processes

Installation

Prerequisites

• Python 3.11 or higher
• uv package manager (recommended) or pip

Install from Source

1. Clone the repository:

   git clone https://github.com/yourusername/adminmcp.git
   cd adminmcp
   

2. Create virtual environment:

   python -m venv .venv
   source .venv/bin/activate  # On Windows: .venv\Scripts\activate
   

3. Install dependencies:

   # Using uv (recommended)
   uv pip install -e .
   
   # Or using pip
   pip install -e .
   

4. Verify installation:

   acp --help
   

Using uv (Recommended)

# Install uv if not already installed
curl -LsSf https://astral.sh/uv/install.sh | sh

# Install AdminMCP
uv pip install -e .

Usage Examples

Basic Server Management

Start the MCP server:

acp server start
# Output: Server started.

Stop the MCP server:

acp server stop
# Output: Server stopped.

Initialize configuration:

acp init
# Output:
# Copied config.adminmcp.json to /home/user/.config/adminmcp/config.adminmcp.json
# Created /home/user/.config/adminmcp/mcp_settings.json
# Configuration initialized.

Testing with MCP Inspector

The easiest way to test the server is using the MCP Inspector:

mcp dev ./src/adminmcp/server/acp_server.py

This starts the MCP Inspector UI where you can interact with all available tools and resources.

Programmatic Usage

The server can be used programmatically through MCP clients. Here are some example tool calls:

# Mathematical operations
result = add(5, 3)  # Returns 8
result = multiply(4, 7)  # Returns 28

# Resource access
pi_value = get_constant("pi")  # Returns 3.141592653589793
is_even = is_even(42)  # Returns True

# DateTime information
current = current_datetime()
# Returns: {"datetime": "2024-01-01T12:00:00+00:00", "timezone": "UTC", "unix_timestamp": 1704110400.0}

# Wikipedia lookup
article = wikipedia_article("Python (programming language)")
# Returns article summary JSON

Configuration

AdminMCP uses a configuration system stored in ~/.config/adminmcp/. The configuration is initialized automatically with the acp init command.

Configuration Files

config.adminmcp.json

Template configuration file with default settings:

{
    "application": {
        "config_folder": "~/.config/adminmcp",
        "log_folder": "~/.local/share/adminmcp/logs",
        "data_folder": "~/.local/share/adminmcp/data",
        "logging_level": "info"
    },
    "server": {
        "port": 8000
    },
    "client": {}
}

mcp_settings.json

Runtime configuration for MCP server settings: …