Skim MCP

🚀 Skim MCP Server

A production-ready Model Context Protocol server for Skim code transformation, built on top of @dean0x's Skim project. It can intelligently compress code for LLM context windows with built-in security, monitoring, and production features.

🚀 Quick Start

If you're using Claude Code (an AI coding assistant), you may encounter "context too long" limitations when analyzing large code projects. Skim MCP Server can automatically compress code, enabling Claude Code to analyze larger projects and providing more accurate code suggestions and analysis.

✨ Features

• 🔒 Secure by Default: Path validation, input sanitization, rate limiting.
• 📊 Production Monitoring: Structured logging, health checks, metrics.
• 🚀 High Performance: Fast execution with spawn, optimized buffering.
• 🛡️ DoS Protection: Request limits, size limits, timeout handling.
• 📝 Comprehensive Logging: Winston integration with configurable levels.
• 🧪 Full Test Coverage: Unit and integration tests included.
• 📦 Zero Dependencies: Only MCP SDK and Winston (production dependencies).

📦 Installation

Prerequisites

• Node.js >= 18.0.0
• npm, pnpm, or yarn

Option 1: Global Install (Recommended)

# Install both MCP server and Skim CLI
npm install -g skim-mcp

# Or install skim CLI separately
npm install -g rskim

Option 2: Project Install

# In your project directory
npm install skim-mcp

Option 3: From Source

git clone https://github.com/luw2007/skim-mcp.git
cd skim-mcp
npm install
npm run build

Automatic Skim Installation

The server automatically installs Skim CLI if not found:

# During npm install (postinstall hook)
npm install skim-mcp

# Or manually
npm run install-skim

Verify Installation

After installation, verify it was successful:

# Check if skim-mcp is available
skim-mcp --version

# Check Node.js version
node --version  # Should be >= 18.0.0

If skim-mcp shows "command not found":

# Check globally installed packages
npm list -g skim-mcp

# Check npm global path
npm config get prefix

You may need to add the npm global path to your system PATH.

🔧 Configuration

Claude Code Settings

Locate and edit your Claude Code configuration file (depending on your operating system):

macOS / Linux:

• ~/.claude/config.json (recommended, try this first)
• or ~/.config/claude-code/config.json

Windows:

• C:\Users\YourUsername\.claude\config.json
• or C:\Users\YourUsername\AppData\Roaming\claude-code\config.json

If the file doesn't exist, create it.

Add the following configuration:

{
  "mcpServers": {
    "skim_mcp": {
      "command": "skim-mcp"
    }
  }
}

⚠️ Important Note

You must completely quit and restart Claude Code for the changes to take effect.

Environment Variables

# Logging level
export LOG_LEVEL=info  # debug, info, warn, error

# Allowed base paths (comma-separated)
export SKIM_ALLOWED_PATHS=/workspace,/home/user/projects

# Rate limiting
export SKIM_MAX_REQUESTS_PER_MINUTE=10

# Input size limit
export SKIM_MAX_INPUT_SIZE=10485760  # 10MB in bytes

Verify Configuration Success

After configuring and restarting Claude Code, test it:

1. Open Claude Code
2. Type in the conversation:

   Help me analyze this project's code structure
   

3. Watch if Claude Code automatically uses the mcp__skim__skim_analyze tool

Success indicators:

• You'll see messages like "Using skim tool to analyze code..." in the conversation
• Or see skim_file / skim_analyze calls in the tool invocation logs

If it doesn't work:

• Check if config file JSON format is valid (use jsonlint.com to validate)
• Confirm you completely quit and restarted Claude Code
• Check Claude Code's log files for error messages

💻 Usage Examples

Basic Usage

Once configured, the tools are automatically available in Claude Code.

Tool 1: skim_transform - Transform Source Code

// Claude Code automatically uses this when analyzing code
mcp__skim__skim_transform({
  source: 'function add(a, b) { return a + b; }',
  language: 'javascript',
  mode: 'structure',
  show_stats: true
})

// Returns:
// function add(a, b)  { /* ... */ }
//
// 📊 Token Reduction Statistics:
// [skim] 24 tokens → 9 tokens (62.5% reduction)

Tool 2: skim_file - Transform Files

mcp__skim__skim_file({
  path: '/workspace/src',
  mode: 'structure',
  show_stats: true
})

// Returns compressed code with statistics

Tool 3: skim_analyze - Architecture Analysis

mcp__skim__skim_analyze({
  path: '/workspace/src',
  mode: 'structure'
})

// Returns:
// 1. Compressed code
// 2. Token statistics
// 3. Analysis framework to guide Claude

Advanced Usage

Scenario 1: Analyzing Project Architecture

You: "Help me analyze the code architecture in src/ directory"

Claude Code:
→ Automatically calls mcp__skim__skim_analyze
→ Compresses code (65% token reduction)
→ Quickly analyzes architecture and provides suggestions

Result: Complete architecture analysis report

Scenario 2: Code Review

You: "Review the code quality of src/auth.ts"

Claude Code:
→ Automatically calls mcp__skim__skim_file
→ Extracts function signatures and key logic
→ Provides detailed code review suggestions

Result: Identifies potential issues and improvement suggestions

Scenario 3: Understanding Large Files

You: "What does this 3000-line file do?"

Claude Code:
→ Automatically calls mcp__skim__skim_transform
→ Compresses to core structure (80% content reduction)
→ Quickly understands main logic

Result: Clear functional overview and workflow explanation

📚 Documentation

Transformation Modes

Supported Languages

• TypeScript / JavaScript
• Python
• Rust
• Go
• Java
• JSON (special structure mode)
• Markdown (header extraction)
• YAML / YML (structure extraction)

CLI Reference

# Transform file
skim file.ts --mode=structure --show-stats

# Transform directory
skim src/ --mode=signatures

# Transform with glob
skim 'src/**/*.ts' --jobs 4

# Clear cache
skim --clear-cache

🔧 Technical Details

The server is built on top of the Skim project, which uses Rust + tree-sitter as the core technology. It provides 60 - 95% code compression capability, enabling Claude Code to analyze larger projects more efficiently.

📄 License

This project is under the MIT License. See LICENSE file for details.

❓ Frequently Asked Questions (Beginners Must Read)

Installation

Q1: Getting "skim-mcp: command not found" Reason: npm global install path is not in your system PATH. Solution:

# Method 1: Find the installation path
npm config get prefix

# Assuming it returns /usr/local, the full path would be:
# /usr/local/bin/skim-mcp

# Method 2: Use the full path in your config file
{
  "mcpServers": {
    "skim_mcp": {
      "command": "/usr/local/bin/skim-mcp"  # Replace with actual path
    }
  }
}

Q2: Node.js version incompatibility error Check your version:

node --version

Must be >= 18.0.0. If your version is too old, visit nodejs.org to download the latest LTS version.

Configuration

Q3: Can't find where the config file is Try these locations in order:

macOS / Linux:

# 1. Check this path first
ls -la ~/.claude/config.json

# 2. If it doesn't exist, check this
ls -la ~/.config/claude-code/config.json

# 3. If neither exists, create the first one
mkdir -p ~/.claude
echo '{"mcpServers":{}}' > ~/.claude/config.json

Windows: Search for config.json in File Explorer, or create it directly at:

C:\Users\YourUsername\.claude\config.json

Q4: Configuration has no effect Checklist:

• [ ] Config file is valid JSON format (use jsonlint.com to validate)
• [ ] Completely quit Claude Code (not minimized, fully quit)
• [ ] Restart Claude Code
• [ ] skim-mcp command works in terminal
• [ ] Check Claude Code logs for error messages

Usage

Q5: When will the tool be automatically used? Claude Code automatically uses Skim when:

• Analyzing large code files or directories
• Code review tasks
• Architecture analysis requests
• Understanding code structure

You don't need to manually invoke it - Claude Code will automatically decide when to use it.

Q6: How do I know Skim is working? Watch Claude Code's conversation window for:

• Tool invocation messages: mcp__skim__skim_file or mcp__skim__skim_analyze
• Token statistics
• Messages like "Compressing code..." or similar

This indicates Skim is working.

Q7: Will Skim modify my code? No! Skim only reads and compresses code for analysis - it will not modify any source files.

🆘 Support

Reporting Issues

Please report issues on GitHub Issues. Include:

• Node.js version (node --version)
• OS and architecture
• Steps to reproduce
• Error logs

Getting Help

• 📖 Documentation: docs/
• 💡 Examples: docs/examples.md
• 💬 Discussions: GitHub Discussions

🔄 Changelog

See CHANGELOG.md for version history.

🔮 Roadmap

v1.1.0 (Next)

• [ ] HTTP transport support
• [ ] WebSocket transport
• [ ] Plugin system
• [ ] Custom transformation rules
• [ ] Integration with more LLM platforms

v1.2.0 (Future)

• [ ] Parallel processing optimization
• [ ] Memory-efficient streaming
• [ ] Advanced caching strategies
• [ ] Metrics dashboard

🙏 Acknowledgments

Special Thanks

Skim Project and its Author @dean0x

This project is an MCP server wrapper built on top of the excellent Skim project created by dean0x. Skim is a powerful code transformation tool written in Rust that provides intelligent code compression capabilities for LLMs.

• Original Project: https://github.com/dean0x/skim
• Core Technology: Rust + tree-sitter
• Contribution: Provides 60 - 95% code compression capability

Without dean0x's outstanding work, this MCP server wouldn't exist. We highly recommend visiting the original project to learn more about the technical details!

Other Acknowledgments

• Model Context Protocol - MCP protocol specification
• tree-sitter - Code parsing engine
• Claude Code team - For providing an excellent AI coding assistant platform
• All developers who have contributed to this project

Made with ❤️ for the LLM community