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:

Entry points: Main file, server initialization
Tool handlers: What each MCP tool actually does
Network code: Any HTTP clients, WebSocket connections
File system access: Read/write operations, paths accessed
Environment handling: What env vars are read and how used
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:

Pull new changes: git fetch origin
Review diff: git diff HEAD origin/main
Re-run the full audit workflow
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

Restart Claude Code - Required for new servers
Verify with /mcp - Shows connected servers
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

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

secure-mcp-install