mcp-proc/docs/QUICKSTART.md

Quick Start Guide

Installation

Option 1: From npm (when published)

npm install -g @mcp/procfs-server

Option 2: From source

git clone https://github.com/cameronrye/activitypub-mcp.git
cd activitypub-mcp/mcp-proc
./scripts/setup.sh

First Run

JSON-RPC Server (stdio)

# Using global install
mcp-procfs

# Or from source
npm start

HTTP Server with SSE

# Default port 3000
npm run start:sse

# Custom port
PORT=8080 npm run start:sse

Open browser to http://localhost:3000/api-docs to explore the API.

Basic Usage Examples

Get System Information

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

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

# Load average
curl http://localhost:3000/api/load

# Network statistics
curl http://localhost:3000/api/network

Process Management

# List all processes
curl http://localhost:3000/api/processes

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

# Set process priority (requires permissions)
curl -X POST http://localhost:3000/api/processes/1234/priority \
  -H "Content-Type: application/json" \
  -d '{"priority": 10}'

Sysctl Operations

# Read parameter
curl http://localhost:3000/api/sysctl/kernel.hostname

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

Using with MCP Client

Claude Desktop Configuration

Edit ~/Library/Application Support/Claude/claude_desktop_config.json:

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

Then restart Claude Desktop and use natural language:

"What's the current CPU usage?"
"Show me memory statistics"
"List all running processes"
"What's the system load average?"

Common Tasks

Monitor System Resources

# Real-time monitoring
node examples/monitoring-dashboard.js

Read Custom ProcFS Files

curl "http://localhost:3000/api/procfs?path=sys/kernel/hostname&format=raw"

Adjust System Parameters

# Check current value
curl http://localhost:3000/api/sysctl/vm.swappiness

# Change value (requires root)
sudo curl -X POST http://localhost:3000/api/sysctl \
  -H "Content-Type: application/json" \
  -d '{"key": "vm.swappiness", "value": 10}'

Troubleshooting

Permission Denied

Some operations require elevated permissions:

# Option 1: Run with sudo (not recommended)
sudo npm run start:sse

# Option 2: Use capabilities
sudo setcap cap_sys_nice,cap_sys_admin+ep $(which node)
npm run start:sse

Port Already in Use

# Use different port
PORT=8080 npm run start:sse

# Or kill existing process
lsof -ti:3000 | xargs kill -9

Cannot Read /proc Files

Ensure you're running on Linux:

uname -s  # Should output: Linux

Check file permissions:

ls -la /proc/cpuinfo
cat /proc/cpuinfo

Next Steps

• Read the full API Documentation
• Check out Examples
• Learn about Development
• Review Security Considerations

Getting Help

• Issues: https://github.com/cameronrye/activitypub-mcp/issues
• Discussions: https://github.com/cameronrye/activitypub-mcp/discussions
• Documentation: https://github.com/cameronrye/activitypub-mcp/tree/master/mcp-proc

Quick Reference

Task	Command
Start JSON-RPC server	mcp-procfs or npm start
Start HTTP server	npm run start:sse
View API docs	http://localhost:3000/api-docs
Get CPU info	curl localhost:3000/api/cpu
Get memory info	curl localhost:3000/api/memory
List processes	curl localhost:3000/api/processes
Read sysctl	curl localhost:3000/api/sysctl/KEY
Health check	curl localhost:3000/health