local-agent-mcp

A personal MCP server that bundles filesystem operations, web search, shell execution, system monitoring, Context7 documentation lookup, and Compound Engineering workflow prompts into a single service.

Designed to run as a persistent HTTP service on your Mac, accessible locally and from any machine on your Tailscale network. Connects to llama-server WebUI, llama-agent CLI, or any MCP-compatible client.

Tools (16)

Category	Tool	Description
Filesystem	read_file	Read file contents
	write_file	Create or overwrite a file
	edit_file	Search-and-replace within a file
	list_directory	List directory contents
	create_directory	Create directories recursively
	move_file	Move or rename files/directories
	search_files	Grep-style recursive content search
	get_file_info	File metadata (size, modified, permissions)
Web	web_search	DuckDuckGo search (no API key needed)
	fetch_url	Fetch a URL, return cleaned text
Shell	shell_exec	Execute shell commands (with safety blocks)
	system_info	OS, CPU, memory, disk, uptime
	list_processes	Running processes, filterable by name
Docs	resolve_library_id	Find Context7 library ID for a package
	get_library_docs	Fetch up-to-date docs for a library
Clipboard	clipboard	Read/write macOS system clipboard

Prompts (3)

Prompt	Description
plan	Turn a feature description into a structured implementation plan
review	Multi-pass code review (scope, correctness, security, performance)
compound	Capture knowledge from a solved problem for future reuse

Quick Start

Prerequisites

• Bun (v1.0+)
• Node.js 18+ (for npx-based tools if needed)

Install

cd ~/Projects/local-agent-mcp
bun install

Configure

cp .env.example .env
# Edit .env — at minimum, generate an auth token:
echo "MCP_AUTH_TOKEN=$(openssl rand -hex 32)" >> .env

Run (HTTP mode)

bun run start:http
# Server at http://0.0.0.0:8808/mcp

Run (stdio mode)

bun run start
# Communicates over stdin/stdout

Connecting to llama.cpp

llama-server WebUI

1. Start llama-server with the MCP proxy flag:

   llama-server -m your-model.gguf --webui-mcp-proxy

2. Start the MCP server in HTTP mode:

   bun run start:http

3. In the WebUI, go to Settings → MCP → Add New Server:

   • URL: http://localhost:8808/mcp (local) or http://<your-mac>.tailnet-name.ts.net:8808/mcp (Tailscale)
   • Enable Use llama-server proxy
   • If auth is enabled, add header: Authorization: Bearer <your-token>

llama-agent CLI

Copy or symlink the mcp.json to your working directory or ~/.config/llama-agent/mcp.json:

cp mcp.json ~/.config/llama-agent/mcp.json

The CLI uses stdio transport, so no auth token is needed.

Tailscale Network Access

When running in HTTP mode, the server listens on 0.0.0.0:8808 by default, making it accessible from any machine on your Tailscale network:

http://<your-mac>.tailnet-name.ts.net:8808/mcp

The Bearer token in MCP_AUTH_TOKEN authenticates all requests. Tailscale handles encryption.

Health Check

curl http://<your-mac>.tailnet-name.ts.net:8808/health
# {"status":"ok","server":"local-agent-mcp"}

Running as a macOS Service

Install the launchd plist to start the server on boot:

# Copy the plist
cp com.local-agent-mcp.plist ~/Library/LaunchAgents/

# Load (start)
launchctl load ~/Library/LaunchAgents/com.local-agent-mcp.plist

# Check status
launchctl list | grep local-agent-mcp

# View logs
tail -f ~/Library/Logs/local-agent-mcp.stderr.log

# Unload (stop)
launchctl unload ~/Library/LaunchAgents/com.local-agent-mcp.plist

The service reads .env from the project directory automatically (Bun auto-loads .env files).

Configuration

All configuration is via environment variables (set in .env or export directly):

Variable	Default	Description
MCP_AUTH_TOKEN	(none)	Bearer token for HTTP auth. Required for production.
ALLOWED_DIRS	$HOME	Comma-separated directories the filesystem tools can access
CONTEXT7_API_KEY	(none)	Optional Context7 API key for higher rate limits
HOST	0.0.0.0	HTTP bind address
PORT	8808	HTTP port
ENABLE_SHELL_EXEC	true	Set to false to disable the shell_exec tool entirely
CORS_ORIGIN	*	Allowed CORS origin. Defaults to * which is required for llama-server WebUI. The Bearer token is the security boundary.

Security Notes

• Authentication: All HTTP requests require a Bearer token via the MCP_AUTH_TOKEN env var. The comparison uses crypto.timingSafeEqual to prevent timing attacks.
• Filesystem sandbox: All file operations are restricted to ALLOWED_DIRS. Symlinks are resolved via realpath to prevent traversal.
• SSRF protection: fetch_url blocks requests to private/loopback/link-local IPs and non-http(s) schemes. DNS resolution is checked before fetching.
• Shell execution: shell_exec has a best-effort blocklist for destructive commands, but it is not a security boundary. Disable it with ENABLE_SHELL_EXEC=false if you don't need it.
• Process listing: list_processes filters in TypeScript (no shell interpolation) to prevent injection.
• Fetch timeouts: All outbound HTTP requests have a 15-second timeout via AbortController.

Extending

Each tool category is a separate file in src/tools/. To add new capabilities:

1. Create src/tools/your-feature.ts
2. Export a registerYourFeatureTools(server: McpServer) function
3. Import and call it in src/server.ts

Potential additions:

• Git operations (status, pull, commit, diff)
• Docker management (list, start, stop containers)
• Home Assistant integration
• Obsidian/notes search
• Tailscale management

License

MIT