Skip to main content
Glama
prmichaelsen

acp-mcp

by prmichaelsen
OverviewSchemaRelated ServersScoreDiscussions
Remote

ACP MCP

MCP server for remote machine operations via SSH. Provides a single, powerful tool for executing any shell command on remote machines with real-time progress streaming.

Installation

npm install @prmichaelsen/acp-mcp

Development

npm install
npm run dev

Build

npm run build

Usage

With Claude Desktop

Add to your Claude Desktop configuration:

{
  "mcpServers": {
    "acp-mcp": {
      "command": "node",
      "args": ["/absolute/path/to/acp-mcp/dist/server.js"]
    }
  }
}

With mcp-auth

import { createServer } from '@prmichaelsen/acp-mcp/factory';
import { readFileSync } from 'fs';

const server = await createServer({
  userId: 'user-123',
  ssh: {
    host: 'remote.example.com',
    port: 22,
    username: 'remote-user',
    privateKey: readFileSync('/path/to/private/key', 'utf-8'),
  },
});

Available Tools

acp-mcp v1.0.0 provides a single, powerful tool for all remote operations:

acp_remote_execute_command

Execute any shell command on the remote machine with optional progress streaming.

Parameters:

  • command (required): Shell command to execute

  • cwd (optional): Working directory for command execution

  • timeout (optional): Timeout in seconds (default: 30, ignored if progress streaming)

Returns: { stdout, stderr, exitCode, timedOut, streamed? }

Features:

  1. Shell Environment (v0.7.1+): Automatically sources shell configuration files

    • Sources ~/.zshrc, ~/.bashrc, or ~/.profile before executing commands

    • Ensures $PATH and environment variables are properly loaded

    • Enables user-installed tools (nvm, homebrew, etc.) to work correctly

    • Gracefully handles missing config files

  2. Progress Streaming (v0.7.0+): Real-time output for long-running commands

    • Requires MCP SDK v1.26.0+ (server and client)

    • Client must provide progressToken in request _meta

    • Client must handle progress notifications via onprogress callback

    • Graceful fallback to timeout mode if no progressToken provided

    • Rate limited to max 10 notifications/second

    • Ideal for: npm run build, npm test, npm run dev

Common Operations

List Files

# Basic listing
acp_remote_execute_command({ command: "ls -la ~/project" })

# Recursive listing
acp_remote_execute_command({ command: "find ~/project -type f" })

# With tree (if installed)
acp_remote_execute_command({ command: "tree ~/project" })

# Only directories
acp_remote_execute_command({ command: "ls -d */ ~/project" })

Read Files

# Read entire file
acp_remote_execute_command({ command: "cat ~/project/package.json" })

# Read first 100 lines
acp_remote_execute_command({ command: "head -n 100 ~/project/large-file.txt" })

# Read last 50 lines
acp_remote_execute_command({ command: "tail -n 50 ~/project/log.txt" })

# Search in file
acp_remote_execute_command({ command: "grep 'pattern' ~/project/file.txt" })

Write Files

# Write simple content
acp_remote_execute_command({ command: "echo 'hello world' > ~/project/file.txt" })

# Write multi-line content
acp_remote_execute_command({ 
  command: "cat > ~/project/file.txt << 'EOF'\nline 1\nline 2\nline 3\nEOF" 
})

# Append to file
acp_remote_execute_command({ command: "echo 'new line' >> ~/project/file.txt" })

# Create directories
acp_remote_execute_command({ command: "mkdir -p ~/project/new/nested/dir" })

File Operations

# Copy files
acp_remote_execute_command({ command: "cp ~/source.txt ~/dest.txt" })

# Move files
acp_remote_execute_command({ command: "mv ~/old.txt ~/new.txt" })

# Delete files
acp_remote_execute_command({ command: "rm ~/file.txt" })

# Change permissions
acp_remote_execute_command({ command: "chmod 755 ~/script.sh" })

Development Operations

# Git operations
acp_remote_execute_command({ command: "git status", cwd: "~/project" })
acp_remote_execute_command({ command: "git commit -m 'message'", cwd: "~/project" })

# Package management
acp_remote_execute_command({ command: "npm install", cwd: "~/project" })
acp_remote_execute_command({ command: "npm run build", cwd: "~/project" })

# Process management
acp_remote_execute_command({ command: "ps aux | grep node" })
acp_remote_execute_command({ command: "kill -9 12345" })

Why Single Tool?

v1.0.0 removed specialized tools (list_files, read_file, write_file) in favor of execute_command:

✅ Properly expands ~ and environment variables - SFTP-based tools didn't ✅ Maximum flexibility - Use any shell command or tool ✅ Simpler codebase - One tool instead of four ✅ More reliable - No SFTP edge cases or limitations ✅ Consistent behavior - Works exactly like interactive SSH ✅ Easier to maintain - Single code path to test and debug

Configuration

Standalone Server Configuration

Copy .env.example to .env and configure SSH credentials:

cp .env.example .env

Edit .env with your SSH connection details:

# SSH Configuration (required)
SSH_HOST=your-remote-server.com
SSH_PORT=22
SSH_USERNAME=your-username
SSH_PRIVATE_KEY_PATH=/path/to/your/ssh/private/key

mcp-auth Configuration

When using with mcp-auth, SSH credentials are provided programmatically:

import { createServer } from '@prmichaelsen/acp-mcp/factory';
import { readFileSync } from 'fs';

// SSH credentials provided by mcp-auth wrapper
const server = await createServer({
  userId: 'user-123',
  ssh: {
    host: process.env.REMOTE_HOST,
    port: parseInt(process.env.REMOTE_PORT || '22'),
    username: process.env.REMOTE_USERNAME,
    privateKey: readFileSync(process.env.REMOTE_KEY_PATH, 'utf-8'),
  },
});

Scripts

  • npm run dev - Start development server with hot reload

  • npm run build - Build for production

  • npm run build:watch - Build and watch for changes

  • npm start - Run production build

  • npm test - Run tests

  • npm run typecheck - Type check without emitting

  • npm run clean - Remove build output

License

MIT

Author

Patrick Michaelsen

This server cannot be installed

A
license - permissive license
-
quality - not tested
B
maintenance

How are these scores calculated?

Maintenance

–Maintainers
1hResponse time
–Release cycle
–Releases (12mo)

Resources

Unclaimed servers have limited discoverability.

Looking for Admin?

If you are the server author, to access and configure the admin panel.

Latest Blog Posts

MCP directory API

We provide all the information about MCP servers via our MCP API.

curl -X GET 'https://glama.ai/api/mcp/v1/servers/prmichaelsen/acp-mcp'

If you have feedback or need assistance with the MCP directory API, please join our Discord server