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

Related MCP server: mcp-infra

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

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