Computer Linker

Expose one folder on your computer as an MCP server.

Use it when you want an MCP client or agent to inspect, edit, test, and work inside a specific local project folder without exposing your whole machine.

Quick Start

Computer Linker requires Node.js 20.12 or newer.

npm install -g @easonwumac/computer-linker
cd C:\Projects\my-app
computer-linker here

Leave that terminal running. In another terminal, print the client settings:

computer-linker client setup --show-token

Use these values in your MCP client:

URL: http://127.0.0.1:3939/mcp
Authorization: Bearer <ownerToken>

That is the normal local workflow.

Open A Folder

Open the current folder:

cd C:\Projects\my-app
computer-linker here

Open a specific folder from anywhere:

computer-linker start C:\Projects\my-app

The scope name defaults to the folder name, so --name is usually not needed.

Permission Modes

Need	Command
Normal coding	computer-linker here
Inspect only	computer-linker here --read-only
Codex operations and screen capture	computer-linker here --full-trust

Normal coding mode allows file edits and approved project commands such as test and build scripts. Use --full-trust only for folders where local agent execution and screen capture are intended.

Cloud MCP Clients

Cloud MCP clients cannot reach 127.0.0.1. Use a tunnel only when the client runs outside your computer.

OpenAI Secure MCP Tunnel:

$env:CONTROL_PLANE_API_KEY = "sk-..."
computer-linker here --tunnel openai --tunnel-id tunnel_...

In the MCP client, choose OpenAI Tunnel mode and use the tunnel_... id. Do not paste the Computer Linker bearer token into OpenAI Tunnel mode.

Tailscale Funnel:

computer-linker here --tunnel tailscale

Cloudflare quick tunnel:

computer-linker here --tunnel cloudflare

Cloudflare hostname you own:

computer-linker here --url https://mcp.your-domain.com --tunnel cloudflare

Public tunnel mode exposes only /mcp to public-host requests. Local /api and /healthz stay local-only diagnostics.

Agent Instructions

Give your MCP agent this short instruction:

First call get_computer_info. Then use computer_operation with {scope, op, target, input, options}. Stay inside the configured scope. Prefer code.context, file.search, file.read, git.diff, and get_operation_history before making changes.
Call computer_operation with dotted ops from computerOperationRegistry.
Do not call workspace_operation, read, ls, grep, glob, or create_file unless the server explicitly exposes compatibility tools.

Main MCP tools:

Tool	Purpose
get_computer_info	Inspect scopes, permissions, URLs, policy, and available operations.
computer_operation	Run one operation inside an approved scope.
get_operation_history	Read redacted recent activity and connection history.

Full pasteable guidance: docs/agent-instructions.md.

Configuration is normally written by the CLI. For manual service deployments, use scopes[] in ~/.computer-linker/config.json; workspaces[] is kept only as a 0.x compatibility mirror. See docs/configuration.md and docs/config.schema.json.

Useful Commands

Need	Command
Start current folder	computer-linker here
Start another folder	computer-linker start C:\Projects\my-app
Show MCP client settings	computer-linker client setup
Show bearer token	computer-linker client setup --show-token
Check install without exposing a project	computer-linker check
Check current server state	computer-linker status
Diagnose client setup	computer-linker diagnose client
See recent connections	computer-linker history --view connections
See tunnel status	computer-linker tunnel status
Advanced help	computer-linker help advanced

Safety Defaults

• One command exposes one configured folder, not the whole computer.
• Tokens are redacted unless you pass --show-token.
• Sensitive file content is blocked by default, including .env*, private keys, credential JSON files, and cloud CLI credentials.
• Public tunnel mode exposes MCP only, not the local diagnostic API.
• Package release scripts such as deploy, publish, and release are denied by default in normal coding scopes.
• Shell, package, process, and Codex operations run as local host processes. Use OS, container, firewall, proxy, or network controls when network isolation matters.

Troubleshooting

Client cannot connect:

computer-linker diagnose client
computer-linker status --details
computer-linker history --view connections

Tunnel does not work:

computer-linker tunnel status
computer-linker client setup

For a running OpenAI tunnel, tunnel status probes tunnel-client's loopback admin API. It reports process state, live, ready, the local MCP probe, recent command activity, and whether tunnel-client itself observed a 401.

OpenAI tunnel returns an organization 401:

Verify the API key's OpenAI Platform organization, Tunnels Read + Use permission, and client workspace association. This is usually an OpenAI tunnel authorization issue, not a Computer Linker workspace issue. If tunnel status reports ready, mcpProbe=ok, and no observed 401, a ChatGPT organization/workspace rejection before the request reached this machine is the likely cause.

Develop From Source

git clone https://github.com/easonwumac/computer-linker.git
cd computer-linker
npm install
npm run dev -- check
npm run dev -- here

Before pushing code changes:

npm run product:check
npm run public:audit -- --strict-history

GitHub Actions intentionally runs the main CI gate on Windows with Node 22 to keep public CI usage small. It runs on pushes to main and pull requests targeting main.

More Documentation

• Documentation Map
• Learning Paths
• Getting Started
• Client Recipes
• CLI Reference
• Agent Instructions
• Agent Playbook
• SDK Quickstart
• Configuration
• Config Schema
• API Compatibility
• Developer Guide
• Security