terminal-mcp

An agent-capable MCP server with terminal access, filesystem control, and persistent memory. Built-in sandboxing, access control, activity logging, and a file-backed memory store — so Claude can run commands, manage files, and remember context across conversations.

---

What it does

terminal-mcp provides 10 tools across two categories:

Terminal Tools

Tool	Access Scope	Description
run_command	Full ROOT_DIR	Execute shell commands with dangerous-command blocking
read_file	Allowed dirs only	Read files from whitelisted paths
write_file	Allowed dirs only	Write/overwrite files in whitelisted paths
list_files	Full ROOT_DIR	Browse directory contents (recursive supported)
run_workflow	Full ROOT_DIR	Named workflows: npm_install, npm_run, python_run, shell_script

Memory Tools

Tool	Description
memory_store	Save a memory with name, type, tags, and content
memory_recall	Retrieve a specific memory by name
memory_search	Search all memories by keyword and/or type
memory_delete	Remove a memory
memory_list	List all stored memories (returns the MEMORY.md index)

Memory System

The memory system gives Claude persistent context that survives across conversations. Memories are stored as individual markdown files with YAML frontmatter inside claude_playground/memory/, with an auto-maintained MEMORY.md index.

Memory Types

Type	Purpose	Example
user	Who the user is, their preferences, expertise	"Senior backend engineer, prefers Go"
feedback	How to approach work (corrections + confirmations)	"Don't mock the database in integration tests"
project	Ongoing work context, goals, deadlines	"Auth rewrite driven by compliance, due March 15"
reference	Pointers to external resources	"Pipeline bugs tracked in Linear project INGEST"
note	General-purpose memory	Anything that doesn't fit above

How it works

claude_playground/
└── memory/
    ├── MEMORY.md              # Auto-generated index (grouped by type)
    ├── user_role.md           # Individual memory files
    ├── feedback_testing.md
    ├── project_auth_rewrite.md
    └── ...

Each memory file looks like:

---
name: testing preferences
type: feedback
tags: [testing, database]
created: 2025-01-15T14:30:00
updated: 2025-01-20T09:15:00
---
Integration tests must hit a real database, not mocks.

**Why:** Prior incident where mock/prod divergence masked a broken migration.

**How to apply:** Any test touching the data layer should use the test database.

The MEMORY.md index is automatically rebuilt whenever a memory is stored or deleted:

# Memory Index

## User
- [user role](user_role.md) — Senior backend engineer, prefers Go

## Feedback
- [testing preferences](feedback_testing.md) — Integration tests must hit a real database

Usage

Claude can use memory tools naturally in conversation:

• "Remember that I prefer concise responses with no trailing summaries"
• "What do you know about the auth rewrite?"
• "Search your memory for anything about testing"
• "Forget the note about the old API endpoint"
• "What's in your memory?"

Safety Features

• Path sandboxing — read_file and write_file restricted to allowed directories
• Dangerous command blocking — rm -rf /, mkfs, disk overwrites, fork bombs blocked
• Dynamic access control — edit path.txt to grant access without restarting
• Activity logging — every action (including memory operations) logged with timestamps
• Configurable root — restrict the entire server to a specific directory tree

Installation

pip install terminal-mcp

Or from source:

git clone https://github.com/koushikmaji/terminal-mcp.git
cd terminal-mcp
pip install -e .

Setup

Configure Claude Desktop

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

To restrict the root directory:

{
  "mcpServers": {
    "terminal": {
      "command": "terminal-mcp",
      "env": {
        "TERMINAL_MCP_ROOT": "/Users/you/projects"
      }
    }
  }
}

Granting File Access

By default, read_file and write_file only work inside $ROOT/claude_playground/. To grant access to additional paths, add them to claude_playground/path.txt:

# One absolute path per line
/Users/you/projects/my-app
/Users/you/Documents/notes

Changes take effect immediately — no restart needed.

Environment Variables

Variable	Default	Description
TERMINAL_MCP_ROOT	$HOME	Base directory for all operations
TERMINAL_MCP_PLAYGROUND	claude_playground	Playground subdirectory name
TERMINAL_MCP_SHELL	/bin/zsh (macOS) or /bin/bash	Shell for command execution
TERMINAL_MCP_TIMEOUT	30	Default command timeout (seconds)

Architecture

                    run_command / list_files / run_workflow
                    ┌─────────────────────────────────────────┐
                    │            Full ROOT_DIR                 │
                    │                                         │
                    │   read_file / write_file                │
                    │   ┌──────────────────────────┐          │
                    │   │   claude_playground/      │          │
                    │   │   + paths in path.txt     │          │
                    │   │                           │          │
                    │   │   memory_*                │          │
                    │   │   ┌────────────────┐      │          │
                    │   │   │ memory/        │      │          │
                    │   │   │  MEMORY.md     │      │          │
                    │   │   │  *.md files    │      │          │
                    │   │   └────────────────┘      │          │
                    │   └──────────────────────────┘          │
                    └─────────────────────────────────────────┘

Logging

All actions are logged to claude_playground/terminal.log:

[2025-01-15 14:32:01] [RUN] CMD: ls -la  |  CWD: /Users/you
[2025-01-15 14:32:05] [READ] FILE: /Users/you/projects/app/config.json
[2025-01-15 14:33:00] [MEMORY] STORE: user role (user)
[2025-01-15 14:33:10] [MEMORY] SEARCH: q=testing type=None hits=2

Requirements

• Python 3.10+
• MCP-compatible client (Claude Desktop, Claude Code, etc.)

License

MIT