Content
# MCP Cursor Allowlist
[](https://www.python.org/downloads/)
[](https://github.com/astral-sh/ruff)
[](https://github.com/modelcontextprotocol/python-sdk)
An MCP (Model Context Protocol) server that collects and provides access to Cursor IDE's command allowlist data. This tool allows you to programmatically retrieve the current state of commands that have been approved for AI execution in Cursor IDE.
## 🚀 Features
- **Real-time Allowlist Access**: Collect current command allowlist from Cursor IDE's SQLite database
- **CLI Sync Tool**: Sync Cursor UI allowlist to global CLI configuration with merge or reset modes
- **MCP Protocol Integration**: Full Model Context Protocol server implementation
- **Point-in-time Snapshots**: Get timestamped allowlist data with metadata
- **Error Handling**: Graceful handling of database access issues and empty allowlists
- **Configuration Management**: Platform-specific configuration file support
- **Automatic Backups**: Timestamped backups before modifying CLI configuration
- **Comprehensive Testing**: 93% test coverage with unit and integration tests
- **Easy Installation**: One-command setup for Cursor IDE integration
## 📁 Project Structure
```
mcp-cursor-allowlist/
├── src/
│ └── mcp_cursor_allowlist/ # Main package
│ ├── __init__.py # Package metadata
│ ├── main.py # Application entry point
│ ├── mcp_server.py # MCP server implementation
│ ├── config.py # Configuration management
│ └── database.py # SQLite database interaction
├── tests/
│ ├── unit/ # Unit tests (99% coverage)
│ │ ├── test_main.py # Main module tests
│ │ ├── test_mcp_server.py # MCP server tests
│ │ ├── test_config.py # Configuration tests
│ │ └── test_database.py # Database tests
│ ├── integration/ # Integration tests
│ └── __init__.py
├── docs/ # Comprehensive documentation
│ ├── REQUIREMENTS.md # Functional and non-functional requirements
│ ├── TEST_PLAN_UNIT.md # Unit test plan
│ ├── TEST_PLAN_INTEGRATION.md # Integration test plan
│ ├── IMPLEMENTATION_PLAN.md # Implementation roadmap
│ ├── architecture/ # System architecture
│ └── research/ # Technical research
├── make/ # Modular Makefile components
├── scripts/
│ ├── test_mcp_client.py # MCP server test client
│ └── update_cursor_config.py # Cursor configuration script
├── Makefile # Main build file
├── pyproject.toml # Python project configuration
└── requirements-dev.txt # Development dependencies
```
## 🛠️ Quick Start
### 1. Clone and Install
```bash
# Clone the repository
git clone <repository-url> mcp-cursor-allowlist
cd mcp-cursor-allowlist
# Set up development environment
make requirements-dev
```
### 2. Install in Cursor IDE
```bash
# Install and configure the MCP server in Cursor IDE
make install-cursor
```
This will:
- Install the package in development mode
- Configure Cursor IDE to use the MCP server
- Update `~/.cursor/mcp.json` with the server configuration
### 3. Restart Cursor IDE
After installation, restart Cursor IDE to enable the MCP server.
### 4. Use the Tools
Once installed, you can use the MCP tools in Cursor IDE:
#### Collect Allowlist Info
Use `collect_allowlist_info` to view current approved commands:
**Example Output:**
```json
{
"timestamp": "2025-08-28T16:31:37.283147",
"source": "cursor_ide",
"allowlist": [
"mkdir", "make", "cat", "ls", "git status",
"git diff", "curl", "jq", "trim", "tree"
],
"total_count": 40,
"note": "This is a point-in-time snapshot. Re-run periodically to refresh."
}
```
#### Sync to CLI Configuration
Use `sync_allowlist_to_cli` to copy approved commands to Cursor CLI:
**Merge Mode** (default - adds to existing CLI permissions):
```json
{
"mode": "merge"
}
```
**Reset Mode** (replaces CLI permissions with only UI allowlist):
```json
{
"mode": "reset",
"create_backup": true
}
```
**Example Response:**
```json
{
"success": true,
"mode": "merge",
"original_count": 10,
"new_count": 15,
"added_count": 5,
"config_path": "/home/user/.cursor/cli-config.json",
"backup_path": "/tmp/cursor-cli-config.backup.20251014_120000.json"
}
```
**Note:** Backups are stored in `/tmp/` for automatic system cleanup, preventing accumulation while still providing recovery during the session.
## 📋 Make Targets
### Essential Commands
```bash
make install-cursor # Install and configure MCP server in Cursor IDE
make test # Run all tests (99% coverage)
make lint # Run linting and type checking
make format # Format code with ruff
```
### Development Commands
```bash
make requirements-dev # Set up development environment
make coverage # Run tests with coverage threshold check
make clean # Clean temporary files and artifacts
make help # Show all available targets
```
### Testing Commands
```bash
make test-unit # Run unit tests only
make test-integration # Run integration tests only
make coverage-report # Generate coverage report without threshold
make coverage-verify # Verify coverage meets 80% threshold
```
## 🔧 How It Works
### MCP Server Architecture
This is a complete MCP (Model Context Protocol) server that integrates with Cursor IDE to provide allowlist data access.
**Key Components:**
1. **MCP Server** (`mcp_server.py`): Implements the Model Context Protocol
2. **Database Module** (`database.py`): Handles SQLite database interaction
3. **Configuration** (`config.py`): Manages platform-specific configuration
4. **Main Entry Point** (`main.py`): Application startup and argument parsing
### Data Source
The server reads Cursor IDE's allowlist from:
- **Database**: `~/.config/Cursor/User/globalStorage/state.vscdb`
- **Table**: `ItemTable`
- **Key**: `src.vs.platform.reactivestorage.browser.reactiveStorageServiceImpl.persistentStorage.applicationUser`
- **Field**: `composerState.yoloCommandAllowlist` (JSON array)
### Configuration
Configuration is stored in `mcp-cursor-allowlist-config.json` in platform-specific locations:
- **Linux**: `~/.cursor/mcp-cursor-allowlist-config.json`
- **macOS**: `~/Library/Application Support/Cursor/User/mcp-cursor-allowlist-config.json`
- **Windows**: `%APPDATA%/Cursor/User/mcp-cursor-allowlist-config.json`
## 🧪 Testing
The project includes comprehensive testing with **99% coverage**:
### Test Structure
- **Unit Tests** (`tests/unit/`): 48 tests covering all modules
- `test_main.py`: Application entry point tests
- `test_mcp_server.py`: MCP server functionality tests
- `test_config.py`: Configuration management tests
- `test_database.py`: Database interaction tests
- **Integration Tests** (`tests/integration/`): End-to-end workflow tests
- **Coverage Threshold**: 80% minimum, currently at 99%
### Running Tests
```bash
make test # Run all tests with coverage
make test-unit # Run unit tests only
make test-integration # Run integration tests only
make coverage # Coverage with 80% threshold check
```
### Test Features
- **Async testing**: Full async/await support with pytest-asyncio
- **Mock database**: Isolated testing without real database dependency
- **Error simulation**: Comprehensive error handling validation
- **Platform testing**: Cross-platform configuration testing
## 📏 Code Quality
### Tools and Standards
- **ruff**: Fast linting and formatting (99% compliance)
- **mypy**: Static type checking with strict mode
- **pytest**: Testing framework with async support
- **Line length**: 88 characters
- **Python target**: 3.10+
### Quality Commands
```bash
make lint # Check code quality (ruff + mypy)
make format # Format code and auto-fix issues
make test # Run tests with coverage
```
### Quality Metrics
- **Test Coverage**: 99% (48 unit tests)
- **Type Coverage**: 100% with mypy strict mode
- **Linting**: Clean ruff validation
- **Documentation**: Comprehensive docstrings and README
## 🚀 Tool Usage
### Available Tools
The MCP server exposes two tools:
1. **`collect_allowlist_info`** - Collect current Cursor UI allowlist
2. **`sync_allowlist_to_cli`** - Sync allowlist to Cursor CLI configuration
### Tool 1: collect_allowlist_info
Retrieves the current allowlist from Cursor IDE's database.
**Input Schema:**
```json
{} // No parameters required
```
**Response Format:**
```json
{
"timestamp": "2025-08-28T16:31:37.283147",
"source": "cursor_ide",
"allowlist": [
"mkdir", "make", "cat", "ls", "git status",
"git diff", "curl", "jq", "trim", "tree"
],
"total_count": 40,
"note": "This is a point-in-time snapshot. Re-run periodically to refresh."
}
```
### Tool 2: sync_allowlist_to_cli
Syncs the Cursor UI allowlist to the global CLI configuration file (`~/.cursor/cli-config.json`).
**Input Schema:**
```json
{
"mode": "merge", // "merge" (add to existing) or "reset" (replace all)
"create_backup": true // Create timestamped backup before modifying
}
```
**Response Format (Success):**
```json
{
"success": true,
"mode": "merge",
"original_count": 10,
"new_count": 15,
"added_count": 5,
"removed_count": 0,
"config_path": "/home/user/.cursor/cli-config.json",
"backup_path": "/tmp/cursor-cli-config.backup.20251014_120000.json",
"synced_commands": ["Shell(ls)", "Shell(cat)", ...],
"source_timestamp": "2025-10-14T12:00:00",
"source": "cursor_ui_database"
}
```
**Backup Location:** Backups are stored in `/tmp/` to avoid accumulation and allow automatic system cleanup while remaining available for recovery during the session.
**Modes:**
- **merge**: Adds UI allowlist commands to existing CLI permissions (default)
- **reset**: Replaces all CLI permissions with only the UI allowlist commands
### Use Cases
**Allowlist Collection:**
- **Allowlist Monitoring**: Track which commands are currently approved
- **Security Auditing**: Review approved commands for security compliance
- **Development Planning**: Understand current AI command permissions
- **Process Documentation**: Document approved workflow commands
- **Integration**: Use allowlist data in other automation tools
**CLI Sync:**
- **CLI Configuration**: Apply UI-approved commands to CLI automatically
- **Consistency**: Keep UI and CLI permissions in sync
- **Backup & Safety**: Automatic backups before modifying CLI config
- **Workflow Migration**: Easily copy working UI permissions to CLI
- **Team Setup**: Share consistent command permissions across environments
### Best Practices
**Allowlist Collection:**
1. **Regular Updates**: Re-run periodically as allowlist changes when you approve/deny commands
2. **Point-in-time Data**: Remember this is a snapshot - allowlist changes frequently
3. **Error Handling**: Empty allowlist is valid; errors indicate system issues
4. **Configuration**: Ensure database path is correct for your system
**CLI Sync:**
1. **Use Merge Mode First**: Start with merge mode to preserve existing CLI permissions
2. **Reset with Care**: Reset mode removes all CLI permissions not in UI allowlist
3. **Backups Enabled**: Always keep `create_backup: true` for safety
4. **Review Changes**: Check `/tmp/cursor-cli-config.backup.*` if you need to revert changes
5. **Sync Regularly**: Keep UI and CLI in sync as you approve new commands
6. **Backup Cleanup**: Backups in `/tmp/` are automatically cleaned by the system
## 🔄 Development Workflow
### Installing for Development
```bash
# Clone and set up
git clone <repository-url> mcp-cursor-allowlist
cd mcp-cursor-allowlist
make requirements-dev
# Install in Cursor IDE
make install-cursor
# Restart Cursor IDE and test
```
### Making Changes
```bash
# Make code changes
# ...
# Run quality checks
make format lint test
# Test with real Cursor data
make install-cursor
# Restart Cursor and test the tool
```
### Testing
```bash
# Unit tests only
make test-unit
# Full test suite with coverage
make test
# Manual testing with MCP client
python scripts/test_mcp_client.py
```
## 🤖 LLM Context and AI Integration
This MCP server is specifically designed for AI assistants like Cursor IDE to access allowlist data.
### Project Context for AI
> "This is an MCP server for Cursor IDE allowlist data collection and synchronization. It provides:
> - Real-time access to Cursor's command allowlist via SQLite database
> - MCP protocol implementation with `collect_allowlist_info` and `sync_allowlist_to_cli` tools
> - CLI configuration sync with merge and reset modes
> - Platform-specific configuration management
> - Automatic backup creation before CLI modifications
> - Comprehensive error handling for database access
> - 93% test coverage with async testing support"
### AI Use Cases
- **Allowlist Monitoring**: "Show me what commands are currently approved in Cursor"
- **Security Review**: "What commands should I audit in my current allowlist?"
- **Workflow Planning**: "Which commands can I safely use for [task]?"
- **Documentation**: "Document the approved commands for this project"
- **CLI Setup**: "Sync my UI-approved commands to Cursor CLI configuration"
- **Permission Migration**: "Copy my working UI permissions to CLI in merge mode"
- **Clean Setup**: "Reset CLI to only use my current UI allowlist"
### Integration Benefits
- **Self-Awareness**: AI can check its own command permissions
- **Dynamic Adaptation**: AI can understand current allowlist limitations
- **Security Transparency**: AI can inform users about approved commands
- **Workflow Optimization**: AI can suggest allowlist updates for workflows
## 🏗️ Technical Architecture
### Design Principles
- **Stateless**: No data persisted between calls
- **Ephemeral**: Fresh data collection on each request
- **Error Resilient**: Distinguishes empty allowlist from system failures
- **Platform Agnostic**: Works across Linux, macOS, and Windows
- **Type Safe**: 100% mypy compliance with strict mode
### Dependencies
```toml
dependencies = [
"mcp>=1.0.0",
"anyio>=3.0.0",
"pydantic>=2.0.0",
]
```
### Configuration Schema
```json
{
"database_path": "~/.config/Cursor/User/globalStorage/state.vscdb",
"database_table": "ItemTable",
"database_key": "src.vs.platform.reactivestorage.browser.reactiveStorageServiceImpl.persistentStorage.applicationUser",
"allowlist_field": "composerState.yoloCommandAllowlist"
}
```
## 📚 Documentation
### Complete Documentation
- **[Functional Requirements](docs/REQUIREMENTS.md)**: System requirements and specifications
- **[Test Plans](docs/TEST_PLAN_UNIT.md)**: Unit and integration test documentation
- **[Architecture](docs/architecture/)**: System architecture and design diagrams
- **[Implementation Plan](docs/IMPLEMENTATION_PLAN.md)**: Development roadmap and phases
- **[Research](docs/research/)**: Technical research on Cursor's allowlist system
### Resources
- [MCP Documentation](https://github.com/modelcontextprotocol/python-sdk)
- [Cursor IDE](https://cursor.com/)
- [SQLite Documentation](https://www.sqlite.org/docs.html)
## 🤝 Contributing
1. Fork the repository
2. Create a feature branch: `git checkout -b feature/my-feature`
3. Make your changes with tests
4. Run quality checks: `make format lint test`
5. Submit a pull request
### Development Standards
- **99% test coverage** minimum
- **Type hints** required for all functions
- **Async/await** for all I/O operations
- **Error handling** for all external dependencies
---
**Collect your Cursor allowlist data! 🎯**
This MCP server provides seamless access to Cursor IDE's command allowlist for AI assistants and automation tools.
