mcp-proc/README.md

MCP ProcFS Server

A powerful Model Context Protocol (MCP) server for reading and modifying Linux /proc filesystem values. Provides both JSON-RPC (stdio) and Server-Sent Events (SSE) interfaces with full Swagger API documentation.

Features

• 🔍 Comprehensive ProcFS Access: Read and write to /proc filesystem
• 🎛️ System Monitoring: CPU, memory, load, network, and disk statistics
• ⚙️ Sysctl Management: Read and modify kernel parameters
• 🔧 Process Control: Monitor and manage processes (priority, affinity, signals)
• 📡 Dual Protocols: JSON-RPC over stdio and HTTP with SSE
• 📚 Full API Documentation: Interactive Swagger UI
• 🔐 Type-Safe: Written in TypeScript with comprehensive type definitions
• ✅ Validated: Zod schemas for request/response validation

Installation

From npm

npm install -g @mcp/procfs-server

From source

git clone https://github.com/user/mcp-proc.git
cd mcp-proc
npm install
npm run build

Quick Start

JSON-RPC Server (stdio)

# Start the MCP server on stdio
mcp-procfs

# Or with npm
npm start

HTTP Server with SSE

# Start HTTP server on port 3000
npm run start:sse

# Custom port
PORT=8080 npm run start:sse

Then open your browser to:

• API Documentation: http://localhost:3000/api-docs
• SSE Endpoint: http://localhost:3000/mcp/sse
• RPC Endpoint: http://localhost:3000/mcp/rpc

Usage

As MCP Tool

Configure in your MCP client (e.g., Claude Desktop):

{
  "mcpServers": {
    "procfs": {
      "command": "mcp-procfs"
    }
  }
}

Available Tools

System Information

• get_cpu_info: Get detailed CPU information
• get_memory_info: Get memory statistics
• get_load_average: Get system load average
• get_network_stats: Get network interface statistics
• get_disk_stats: Get disk I/O statistics

ProcFS Operations

• read_procfs: Read any file from /proc
• write_procfs: Write to writable /proc files

Process Management

• get_process_info: Get detailed process information
• list_processes: List all process IDs
• set_process_priority: Change process nice value
• set_process_affinity: Set CPU affinity

Sysctl Management

• read_sysctl: Read kernel parameter
• write_sysctl: Modify kernel parameter
• list_sysctl: List all parameters

Example: Using HTTP API

# Get CPU information
curl http://localhost:3000/api/cpu

# Get memory information
curl http://localhost:3000/api/memory

# Read a sysctl parameter
curl http://localhost:3000/api/sysctl/net.ipv4.ip_forward

# Write a sysctl parameter (requires permissions)
curl -X POST http://localhost:3000/api/sysctl \
  -H "Content-Type: application/json" \
  -d '{"key": "net.ipv4.ip_forward", "value": 1}'

# Get process information
curl http://localhost:3000/api/processes/1

# Read custom procfs file
curl "http://localhost:3000/api/procfs?path=sys/kernel/hostname"

Example: Using JSON-RPC

import { MCPProcFSServer } from '@mcp/procfs-server';

const server = new MCPProcFSServer();
await server.run();

Example: Direct Library Usage

import { ProcFSReader, ProcFSWriter } from '@mcp/procfs-server';

const reader = new ProcFSReader();
const writer = new ProcFSWriter();

// Get CPU info
const cpuInfo = await reader.getCPUInfo();
console.log(cpuInfo);

// Get memory info
const memInfo = await reader.getMemInfo();
console.log(memInfo);

// Read sysctl
const param = await writer.readSysctl('net.ipv4.ip_forward');
console.log(param);

// Write sysctl (requires root)
await writer.writeSysctl('net.ipv4.ip_forward', 1);

API Documentation

When running the HTTP server, full interactive API documentation is available at:

http://localhost:3000/api-docs

The documentation includes:

• All endpoints with request/response schemas
• Try-it-out functionality
• Example requests and responses
• Authentication requirements

API Endpoints

Method	Endpoint	Description
GET	/health	Health check
GET	/api/cpu	CPU information
GET	/api/memory	Memory information
GET	/api/load	Load average
GET	/api/network	Network statistics
GET	/api/disk	Disk statistics
GET	/api/procfs	Read procfs file
POST	/api/procfs	Write procfs file
GET	/api/sysctl	List sysctl parameters
GET	/api/sysctl/:key	Read sysctl parameter
POST	/api/sysctl	Write sysctl parameter
GET	/api/processes	List all processes
GET	/api/processes/:pid	Get process info
POST	/api/processes/:pid/priority	Set process priority
GET	/mcp/sse	SSE endpoint
POST	/mcp/rpc	JSON-RPC endpoint

MCP Resources

The server exposes the following MCP resources:

• procfs://cpuinfo - CPU information
• procfs://meminfo - Memory information
• procfs://loadavg - Load average
• procfs://net/dev - Network statistics
• procfs://diskstats - Disk statistics

Permissions

Some operations require elevated permissions:

• Read-only operations: Most read operations work without special permissions
• Write operations: Require appropriate permissions (usually root)
• Process management: Some operations require CAP_SYS_NICE or root
• Sysctl writes: Usually require root or specific capabilities

Running with elevated permissions

# Run with sudo (not recommended for production)
sudo mcp-procfs

# Better: Use capabilities
sudo setcap cap_sys_nice,cap_sys_admin+ep $(which node)
mcp-procfs

Development

Setup

npm install
npm run build

Development Mode

npm run dev  # Watch mode with hot reload

Testing

npm test              # Run tests
npm run test:watch    # Watch mode
npm run test:coverage # Coverage report

Linting

npm run lint          # Check code
npm run format        # Format code

Architecture

mcp-proc/
├── src/
│   ├── lib/
│   │   ├── procfs-reader.ts    # ProcFS reading logic
│   │   └── procfs-writer.ts    # ProcFS writing logic
│   ├── types/
│   │   ├── procfs.ts           # ProcFS type definitions
│   │   ├── mcp.ts              # MCP protocol types
│   │   └── schemas.ts          # Zod validation schemas
│   ├── server.ts               # MCP JSON-RPC server
│   ├── server-sse.ts           # HTTP/SSE server
│   ├── cli.ts                  # JSON-RPC CLI entry
│   ├── cli-sse.ts              # HTTP/SSE CLI entry
│   └── index.ts                # Main exports
├── scripts/
│   ├── setup.sh                # Setup script
│   ├── build.sh                # Build script
│   └── release.sh              # Release script
└── tests/                      # Test files

Technology Stack

• Runtime: Node.js 18+
• Language: TypeScript
• Validation: Zod
• Web Framework: Express
• Documentation: Swagger/OpenAPI
• MCP SDK: @modelcontextprotocol/sdk
• Testing: Jest

Security Considerations

⚠️ Important Security Notes:

1. This server provides direct access to system resources
2. Write operations can affect system behavior
3. Always run with minimum required permissions
4. Consider using read-only mode for untrusted clients
5. Implement authentication for production deployments
6. Monitor and log all write operations

Contributing

Contributions are welcome! Please:

1. Fork the repository
2. Create a feature branch
3. Make your changes with tests
4. Submit a pull request

License

MIT License - see LICENSE file for details

Resources

• Model Context Protocol Specification
• Linux /proc Documentation
• sysctl Documentation

Support

• Issues: GitHub Issues
• Discussions: GitHub Discussions

Changelog

See CHANGELOG.md for version history.

---

Made with ❤️ for the MCP community