mcp-cli-scripts

# MCP CLI Scripts Pattern

**Status**: Production Ready
**Last Updated**: 2026-01-09
**Dependencies**: tsx (dev dependency)
**Current Versions**: tsx@4.21.0

---

## Why CLI Scripts Alongside MCP Servers?

When building MCP servers, also create companion CLI scripts that provide the same (and often extended) functionality for use with Claude Code in terminal environments.

| Aspect | Remote MCP (Claude.ai) | CLI Scripts (Claude Code) |
|--------|------------------------|---------------------------|
| Context | Results flow through model context window | Results stay local, only relevant parts shared |
| File System | No access | Full read/write access |
| Batch Operations | One call at a time | Can process files of inputs |
| Caching | Stateless | Can cache results locally |
| Output | JSON to model | JSON, CSV, table, file, or stdout |
| Chaining | Model orchestrates | Scripts can pipe/chain directly |

---

## Directory Structure

```
mcp-{name}/
├── src/
│   └── index.ts              # MCP server (for Claude.ai, remote clients)
├── scripts/
│   ├── {tool-name}.ts        # One script per tool
│   ├── {another-tool}.ts
│   └── _shared.ts            # Shared auth/config helpers (optional)
├── SCRIPTS.md                # Documents available scripts for Claude Code
├── package.json
└── README.md
```

---

## The 5 Design Principles

### 1. One Script Per Tool

Each script does one thing well, matching an MCP tool but with extended capabilities.

### 2. JSON Output by Default

Scripts output JSON to stdout for easy parsing. Claude Code can read and use the results.

```typescript
// Good - structured output
console.log(JSON.stringify({ success: true, data: result }, null, 2));

// Avoid - unstructured text (unless --format text requested)
console.log("Found 5 results:");
```

### 3. Extended Capabilities for Local Use

CLI scripts can offer features that don't make sense for remote MCP:

```typescript
// Input/Output files
--input data.csv          // Batch process fro