How do I use terminal-mcp?

1. Click on "Install Server". 2. Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state. 3. In the chat, type @ followed by the MCP server name and your instructions, e.g., "@terminal-mcp Remember that I like concise responses" That's it! The server will respond to your query, and you can continue using it as needed. Here is a step-by-step guide with screenshots.

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

terminal-mcp

terminal-mcp

What it does

Terminal Tools

Memory Tools

Memory System

Memory Types

How it works

Usage

Safety Features

Installation

Setup

Configure Claude Desktop

Granting File Access

Environment Variables

Architecture

Logging

Requirements

License

Resources

Looking for Admin?

Latest Blog Posts

MCP directory API