@genar/knip-mcp-server

A Model Control Protocol (MCP) server that integrates with knip.dev to help AI agents identify and clean up unused files, imports, exports, and dependencies in JavaScript/TypeScript projects.

Overview

This MCP server provides AI agents with powerful code cleanup capabilities through knip.dev integration. It's designed to work seamlessly with Cursor AI and other MCP-compatible tools to maintain clean, efficient codebases.

Features

- Code Analysis: Run comprehensive knip analysis to find unused code
- Unused File Detection: Identify files that are no longer referenced
- Import/Export Cleanup: Find and remove unused imports and exports
- Dependency Management: Detect unused npm dependencies and devDependencies
- Safe Operations: Built-in safety checks and backup mechanisms
- Workspace Support: Full support for monorepo and workspace setups
- Dry Run Mode: Preview changes before applying them

Installation

``bash
npm install -g @genar/knip-mcp-server
`

Or in your project:

`bash
npm install @genar/knip-mcp-server
`

Usage

$3

Run the server directly:

`bash
knip-mcp-server
`

Or use npx:

`bash
npx @genar/knip-mcp-server
`

$3

Configure via environment variables:

`bash
export KNIP_PROJECT_ROOT="/path/to/your/project"
export KNIP_CONFIG_PATH="/path/to/knip.json"
export KNIP_BACKUP_DIR="/path/to/backups"
export KNIP_LOG_LEVEL="info"
export KNIP_SAFE_MODE="true"
`

$3

#### Option 1: MCP Server Configuration

1. In Cursor AI settings, navigate to MCP configuration
2. Add a new MCP server:
- Name: "Knip Code Cleanup"
- Command: npx @genar/knip-mcp-server
3. Save and restart Cursor AI

#### Option 2: Cursor Rules Configuration

You can also integrate this MCP server through Cursor's rules system by creating a .cursor/rules directory in your project root and adding the following configuration:

1. Create the rules directory structure:
`bash
mkdir -p .cursor/rules
`

2. Create a knip rule file (.cursor/rules/knip-mcp.md):

`markdown


Knip Code Cleanup Rules

You have access to the Knip MCP server for code cleanup tasks. Use these tools proactively to maintain clean code:

Available Tools

- knip_scan - Run comprehensive code analysis
- knip_get_unused_files - Find unused files
- knip_get_unused_exports - Find unused exports
- knip_get_unused_imports - Find unused imports
- knip_get_unused_dependencies - Find unused dependencies
- knip_remove_unused_files - Safely remove unused files
- knip_remove_unused_imports - Clean up unused imports
- knip_fix_issues - Auto-fix common issues
- knip_get_config - View knip configuration
- knip_validate_config - Validate knip config

Usage Guidelines

1. After implementing features: Always run knip_scan to identify cleanup opportunities
2. Before commits: Use knip_fix_issues with dryRun: true to preview cleanup
3. Regular maintenance: Run knip_get_unused_dependencies to audit packages
4. Safety first: Always use dry-run mode first, create backups for destructive operations

Workflow Integration

When asked to implement features:
1. Complete the implementation
2. Run knip_scan to analyze unused code
3. Use knip_remove_unused_imports to clean imports
4. Check knip_get_unused_files for orphaned files
5. Apply fixes with appropriate safety measures

Safety Measures

- All destructive operations default to dry-run mode
- Backups are created automatically before modifications
- File limits prevent accidental bulk deletions
- Safe mode protects critical files (package.json, etc.)

Remember: Always review suggestions before applying changes to ensure they don't break functionality.
`

3. Create a main rules file (.cursor/rules/main.md) that includes knip rules:

`markdown


Project Development Rules

Include code cleanup and maintenance guidelines.

@knip-mcp.md

Code Quality Standards

- Use the Knip MCP server for regular code cleanup
- Maintain clean imports and remove unused dependencies
- Follow the knip workflow after feature implementation
`

4. Optional: Add to your .gitignore if you want to keep rules private:
`bash
echo ".cursor/" >> .gitignore
`

#### Option 3: Per-Project MCP Configuration

Create a local MCP configuration file in your project root (.mcp-config.json):

`json
{
"servers": {
"knip": {
"command": "npx",
"args": ["@genar/knip-mcp-server"],
"env": {
"KNIP_PROJECT_ROOT": ".",
"KNIP_LOG_LEVEL": "info",
"KNIP_SAFE_MODE": "true"
}
}
}
}
`

Then reference this configuration in Cursor's MCP settings.

Available Tools

$3

Run comprehensive knip analysis on your project.

Parameters:
- projectPath (optional): Project path to analyze
- workspace (optional): Specific workspace for monorepos
- includePaths (optional): Array of paths to include
- excludePaths (optional): Array of paths to exclude
- dryRun (default: true): Run without making changes

$3

Get a list of unused files in the project.

Parameters:
- workspace (optional): Specific workspace to analyze

$3

Get unused exports organized by file.

Parameters:
- workspace (optional): Specific workspace to analyze
- filePath (optional): Get exports for specific file only

$3

Get unused imports organized by file.

Parameters:
- workspace (optional): Specific workspace to analyze
- filePath (optional): Get imports for specific file only

$3

Get unused npm dependencies and devDependencies.

Parameters:
- workspace (optional): Specific workspace to analyze
- type (optional): 'dependencies', 'devDependencies', or 'all'

$3

Safely remove unused files with backup options.

Parameters:
- files (optional): Specific files to remove, or all if empty
- dryRun (default: true): Preview mode
- createBackup (default: true): Create backups before removal
- backupDir (optional): Custom backup directory
- maxFiles (default: 50): Safety limit

$3

Remove unused imports from a specific file.

Parameters:
- filePath (required): File to clean up
- imports (optional): Specific imports to remove
- dryRun (default: true): Preview mode
- createBackup (default: true): Create backup before changes

$3

Automatically fix common knip issues.

Parameters:
- issueTypes (default: ['imports']): Types of issues to fix
- dryRun (default: true): Preview mode
- createBackup (default: true): Create backups
- maxFiles (default: 25): Safety limit

$3

Get the current knip configuration.

Parameters:
- projectPath (optional): Project path
- configPath (optional): Specific config file path

$3

Validate knip configuration for correctness.

Parameters:
- projectPath (optional): Project path
- configPath (optional): Specific config file path
- config (optional): Configuration object to validate

Example AI Agent Workflows

$3

`
AI Agent: I just implemented a new authentication feature. Let me clean up any unused code.

1. Run knip_scan to get overview of unused code
2. Use knip_get_unused_imports to find unused imports
3. Apply knip_remove_unused_imports to clean up imports
4. Check knip_get_unused_files for any orphaned files
5. Safely remove files using knip_remove_unused_files
`

$3

`
AI Agent: Let me audit our dependencies for unused packages.

1. Run knip_get_unused_dependencies
2. Review the list of unused dependencies
3. Generate recommendation report for package.json cleanup
`

$3

`
AI Agent: Let me analyze the overall health of this codebase.

1. Run knip_scan for comprehensive analysis
2. Use knip_validate_config to check configuration
3. Generate health report with recommendations
`

Safety Features

- Dry Run Mode: All destructive operations default to dry-run mode
- Backup Creation: Automatic backups before file modifications
- Safe Mode: Prevents removal of critical files (package.json, etc.)
- File Limits: Configurable limits on batch operations
- Error Handling: Comprehensive error reporting and recovery

Configuration

The server supports knip configuration files:
- knip.json
- knip.jsonc
- .knip.json
- .knip.jsonc
- knip.config.js
- knip.config.ts

Development

`bash


Clone the repository

git clone https://github.com/genar/galleries.git
cd galleries/packages/knip-mcp-server

Install dependencies

npm install

Build the project

npm run build

Run in development mode

npm run dev

Run tests

npm test
``

Contributing

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Add tests
5. Submit a pull request

License

MIT License - see LICENSE file for details.

Support

- GitHub Issues: Report bugs or request features
- Documentation: Full documentation

Related Projects

- knip.dev - The underlying code analysis tool
- MCP SDK - Model Context Protocol implementation
- Cursor AI - AI-powered code editor with MCP support