hartreeworks/secure-mcp-install

Secure MCP Server Installation

This skill provides a security-focused workflow for installing MCP servers from third-party sources. It implements a "trust but verify" approach: clone the repository at a specific commit, run automated security scans, perform manual review of critical areas, then install with updates disabled.

When to Use This Skill

Use this workflow when:

• Installing MCP servers from community maintainers (not official Anthropic packages)
• The repository has popularity/stars but unknown maintainers
• Security is a concern but full code review isn't practical
• Pinning to a specific version is desired

Core Workflow

Step 1: Clone at Specific Commit

Clone the repository and check out the target commit:

# Create audit directory
mkdir -p ~/.claude/mcp-audits
cd ~/.claude/mcp-audits

# Clone the repository
git clone <REPO_URL> <SERVER_NAME>
cd <SERVER_NAME>

# Check out specific commit (or latest if user doesn't specify)
git checkout <COMMIT_SHA>

# Record the commit for the audit report
git log -1 --format="%H %ci %s" > ../<SERVER_NAME>-audit-commit.txt

Step 2: Run Automated Security Scan

Execute the audit script to scan for red flags:

~/.claude/skills/secure-mcp-install/scripts/audit-mcp-server.sh ~/.claude/mcp-audits/<SERVER_NAME>

The script scans for:

• Dangerous code patterns (eval, exec, dynamic imports)
• Obfuscated or minified source code
• Suspicious network calls and hardcoded URLs
• Environment variable access patterns
• Credential harvesting indicators
• Known malware signatures

Review the output. Any HIGH severity findings require manual investigation before proceeding.

Step 3: Audit Dependencies

For Node.js projects:

cd ~/.claude/mcp-audits/<SERVER_NAME>
npm audit --audit-level=high
# Or with yarn:
yarn audit --level high

For Python projects:

cd ~/.claude/mcp-audits/<SERVER_NAME>
pip-audit -r requirements.txt 2>/dev/null || pip install pip-audit && pip-audit -r requirements.txt

Check for:

• Known vulnerabilities in dependencies
• Typosquatted package names (check suspicious packages manually)
• Unusually low download counts on dependencies
• Recent ownership transfers on critical packages

Step 4: Manual Review (Focus Areas)

Perform targeted manual review of these critical areas:

1. Entry points: Main file, server initialization
2. Tool handlers: What each MCP tool actually does
3. Network code: Any HTTP clients, WebSocket connections
4. File system access: Read/write operations, paths accessed
5. Environment handling: What env vars are read and how used
6. Build scripts: postinstall hooks, build commands

Refer to references/audit-checklist.md for the complete checklist.

Step 5: Generate Audit Report

Create a report documenting the audit:

# Create report
cat > ~/.claude/mcp-audits/<SERVER_NAME>-audit-report.md << 'EOF'
# MCP Server Audit Report

## Server Details
- **Name**: <SERVER_NAME>
- **Repository**: <REPO_URL>
- **Commit**: <COMMIT_SHA>
- **Audit Date**: $(date -I)

## Automated Scan Results
<PASTE_SCAN_OUTPUT>

## Dependency Audit
<PASTE_DEPENDENCY_AUDIT>

## Manual Review Notes
<YOUR_NOTES>

## Decision
- [ ] APPROVED - Safe to install
- [ ] REJECTED - Security concerns identified
- [ ] CONDITIONAL - Safe with restrictions (document below)

## Restrictions/Notes
<ANY_RESTRICTIONS>
EOF

Step 6: Install with Pinned Version

If approved, install the MCP server at the audited commit.

For npm-based servers, install from the local clone:

cd ~/.claude/mcp-audits/<SERVER_NAME>
npm install
npm run build  # if needed

Then register with Claude Code using the CLI (required - manual file edits don't persist):

# For Node.js servers
claude mcp add-json <SERVER_NAME> '{
  "type": "stdio",
  "command": "node",
  "args": ["'$HOME'/.claude/mcp-audits/<SERVER_NAME>/dist/index.js"],
  "env": {
    "API_KEY": "your-key"
  }
}'

# For Python servers
claude mcp add-json <SERVER_NAME> '{
  "type": "stdio",
  "command": "'$HOME'/.claude/mcp-audits/<SERVER_NAME>/.venv/bin/python",
  "args": ["-m", "<module_name>"],
  "cwd": "'$HOME'/.claude/mcp-audits/<SERVER_NAME>",
  "env": {
    "API_KEY": "your-key"
  }
}'

For Python servers, first create the venv:

cd ~/.claude/mcp-audits/<SERVER_NAME>
python -m venv .venv
source .venv/bin/activate
pip install -e .

Important: Use claude mcp add-json - manually editing ~/.claude.json gets overwritten on restart.

Step 7: Disable Automatic Updates

Since the server is installed from a local clone (not npm/pip registry), updates won't happen automatically. To upgrade later:

1. Pull new changes: git fetch origin
2. Review diff: git diff HEAD origin/main
3. Re-run the full audit workflow
4. Checkout new commit if approved

Quick Reference

| Step | Command/Action | |------|----------------| | Clone | git clone <url> && git checkout <sha> | | Scan | ~/.claude/skills/secure-mcp-install/scripts/audit-mcp-server.sh <path> | | Deps (npm) | npm audit --audit-level=high | | Deps (pip) | pip-audit -r requirements.txt | | Install | From local clone, not registry | | Config | claude mcp add-json <name> '<json>' |

Claude Code MCP Configuration Reference

Adding MCP Servers (Use CLI)

Always use the CLI - manually editing ~/.claude.json gets overwritten on restart:

# Add from JSON config
claude mcp add-json <name> '{"type": "stdio", "command": "...", "args": [...]}'

# Add stdio server with flags
claude mcp add <name> --transport stdio -- <command> <args>

# List configured servers
claude mcp list

# Remove a server
claude mcp remove <name>

Config Scopes

| Scope | Method | Use Case | |-------|--------|----------| | User | claude mcp add-json | Personal servers, all projects | | Project | .mcp.json file in project root | Team-shared, committed to git |

Note: For project scope, you CAN edit .mcp.json directly - only ~/.claude.json gets overwritten.

After Adding

1. Restart Claude Code - Required for new servers
2. Verify with /mcp - Shows connected servers
3. Or use: claude mcp list

Common Issues

• Windows: Wrap npx with cmd /c npx ...
• Project scope: Requires approval on first use
• Environment vars: Support ${VAR} and ${VAR:-default} expansion
• Manual edits to ~/.claude.json: Get overwritten - use CLI instead

Security Principles

1. Pin versions: Never use latest or auto-updating installs
2. Local installs: Install from audited local clone, not registry
3. Minimal env: Only pass required environment variables
4. Document decisions: Keep audit reports for future reference
5. Re-audit on upgrade: Treat updates as new installs

Additional Resources

Reference Files

• references/red-flags.md - Detailed patterns the scanner looks for
• references/audit-checklist.md - Complete manual review checklist

Scripts

• scripts/audit-mcp-server.sh - Automated security scanner