mcp-cli-scripts

MCP CLI Scripts Pattern

Status: Production Ready Last Updated: 2026-01-09 Dependencies: tsx (dev dependency) Current Versions: [email protected]

---

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.

// 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:

// Input/Output files
--input data.csv          // Batch process from file
--output results.json     // Save results to file
--append                  // Append to existing file

// Caching
--cache                   // Use local cache
--cache-ttl 3600          // Cache for 1 hour
--no-cache                // Force fresh request

// Output formats
--format json|csv|table   // Different output formats
--quiet                   // Suppress non-essential output
--verbose                 // Extra debugging info

// Batch operations
--batch                   // Process multiple items
--concurrency 5           // Parallel processing limit

4. Consistent Argument Patterns

Use consistent patterns across all scripts:

# Standard patterns
--input <file>            # Read input from file
--output <file>           # Write output to file
--format <type>           # Output format
--profile <name>          # Auth profile (for multi-account)
--verbose                 # Debug output
--help                    # Show usage

5. Shebang and Direct Execution

Scripts should be directly executable:

#!/usr/bin/env npx tsx
/**
 * Brief description of what this script does
 *
 * Usage:
 *   npx tsx scripts/tool-name.ts <required-arg>
 *   npx tsx scripts/tool-name.ts --option value
 *
 * Examples:
 *   npx tsx scripts/tool-name.ts 12345
 *   npx tsx scripts/tool-name.ts --input batch.csv --output results.json
 */

---

Critical Rules

Always Do

✅ Use #!/usr/bin/env npx tsx shebang (not node or ts-node) ✅ Output JSON to stdout by default ✅ Use consistent argument patterns across all scripts ✅ Document scripts in SCRIPTS.md ✅ Handle errors with structured JSON: { success: false, error: "..." }

Never Do

❌ Use console.log() for prose output (use structured JSON) ❌ Use different argument patterns per script ❌ Forget to document the script in SCRIPTS.md ❌ Use node or ts-node in shebang (tsx handles ESM+TypeScript)

---

When to Use Scripts vs MCP

Use CLI scripts when:

• Working in terminal/Claude Code environment
• Need to save results to files
• Processing batch inputs from files
• Chaining multiple operations
• Need caching for repeated lookups
• Want richer output formats

Use MCP tools when:

• In Claude.ai web interface
• Simple one-off lookups
• No file I/O needed
• Building conversational flows

---

Shared Code Between MCP and Scripts

If you want to share logic between MCP and scripts, extract to a core module:

src/
├── core/
│   ├── lookup.ts         # Pure function, no I/O assumptions
│   └── index.ts          # Export all core functions
├── mcp/
│   └── index.ts          # MCP handlers, import from core
└── cli/
    └── lookup.ts         # CLI wrapper, import from core

However, keeping them separate is also fine - the scripts may evolve to have capabilities the MCP can't support, and that's okay.

---

Using Bundled Resources

Templates (templates/)

script-template.ts: Complete TypeScript script template with argument parsing, JSON output, and file I/O patterns.

# Copy to your project
cp ~/.claude/skills/mcp-cli-scripts/templates/script-template.ts scripts/new-tool.ts

SCRIPTS-TEMPLATE.md: Template for documenting available scripts in an MCP server repo.

# Copy to your project
cp ~/.claude/skills/mcp-cli-scripts/templates/SCRIPTS-TEMPLATE.md SCRIPTS.md

Rules (rules/)

mcp-cli-scripts.md: Correction rules for script files. Copy to .claude/rules/ in projects:

cp ~/.claude/skills/mcp-cli-scripts/rules/mcp-cli-scripts.md .claude/rules/

---

Dependencies

Required:

• [email protected] - TypeScript execution without compilation

Add to package.json:

{
  "devDependencies": {
    "tsx": "^4.21.0"
  }
}

---

Official Documentation

• tsx: https://github.com/privatenumber/tsx
• Node.js CLI: https://nodejs.org/api/cli.html

---

Package Versions (Verified 2026-01-09)

{
  "devDependencies": {
    "tsx": "^4.21.0"
  }
}

---

Complete Setup Checklist

• Create scripts/ directory in MCP server project
• Add tsx to devDependencies
• Create first script from template
• Create SCRIPTS.md from template
• Test script: npx tsx scripts/tool-name.ts --help
• Verify JSON output format
• Document all scripts in SCRIPTS.md