MCP Claude Desktop

A Model Context Protocol (MCP) server that enables Claude Code to communicate with Claude Desktop. This server allows Claude Code to send prompts to Claude Desktop and poll for responses.

Inspired by claude-chatgpt-mcp, this project adapts the concept for Apple's ecosystem using native macOS automation.

Features

• Send prompts from Claude Code to Claude Desktop
• Automatic polling for responses with configurable timeout
• List available conversations in Claude Desktop
• Error handling and retry logic
• Comprehensive logging

Installation

You can install and use this MCP server in two ways:

Option 1: Using npx (Recommended)

The simplest way to use this server is directly with npx, without any installation:

{
  "mcpServers": {
    "claude-desktop": {
      "command": "npx",
      "args": ["mcp-claude-desktop"]
    }
  }
}

Option 2: Local Installation

1. Clone this repository:

git clone https://github.com/dpaluy/mcp-claude-desktop
cd mcp-claude-desktop

2. Install dependencies:

npm install

3. Build the project:

npm run build

4. Configure MCP:

{
  "mcpServers": {
    "claude-desktop": {
      "command": "node",
      "args": ["/path/to/mcp-claude-desktop/dist/index.js"]
    }
  }
}

System Requirements

• macOS 11.0+ (Big Sur or later)
• Node.js 18+
• Claude Desktop app installed
• Accessibility permissions granted for AppleScript

Granting Accessibility Permissions

1. Open System Preferences > Security & Privacy > Privacy
2. Select "Accessibility" from the left sidebar
3. Click the lock to make changes
4. Add Terminal (or your terminal app) to the allowed apps
5. Restart your terminal

MCP Tools

This MCP server provides two tools:

ask

• Purpose: Send a prompt to Claude Desktop and get a response
• Parameters:
  • prompt: The text to send to Claude Desktop (required)
  • conversationId: Optional ID to continue a specific conversation
  • timeout: Response timeout in seconds (optional, default: 30, max: 300)
  • pollingInterval: How often to check for response in seconds (optional, default: 1.5, min: 0.5)

get_conversations

• Purpose: Get a list of available conversations in Claude Desktop
• Parameters: None

Usage

Once configured, Claude Code can use the MCP in various ways:

General Purpose Usage

When Claude uses these tools, it will call them with parameters like:

Basic usage:

• Tool: ask
• Parameters: { "prompt": "What is dependency injection?" }

With custom timeout:

• Tool: ask
• Parameters: { "prompt": "Explain quantum computing", "timeout": 120 }

With both timeout and polling interval:

• Tool: ask
• Parameters: { "prompt": "Quick question", "timeout": 10, "pollingInterval": 0.5 }

Get conversations:

• Tool: get_conversations
• Parameters: {}

How to Use in Claude

Once the MCP server is configured and running, you can use these tools directly in Claude:

Basic usage:

• "Use the ask tool to ask Claude Desktop: What are the best practices for error handling in Python?"
• "Use get_conversations to list all my Claude Desktop conversations"

With custom timeout:

• "Use the ask tool with timeout 60 to ask Claude Desktop: Explain B+ tree implementation"
• "Use ask with timeout 10 and pollingInterval 0.5 to ask Claude Desktop: What is 2+2?"

Important: The MCP server configuration (shown above) only tells Claude how to start the server. The timeout and pollingInterval parameters are specified when you use the tool in Claude, not in the server configuration file.

Known Limitations

Response Reading

Due to Claude Desktop's Electron-based architecture, this MCP integration cannot read Claude's responses programmatically. The tool can successfully:

• ✅ Send prompts to Claude Desktop
• ✅ Create new conversations
• ✅ Activate and focus the Claude window
• ❌ Read Claude's responses back

This is a limitation of how Electron apps expose UI elements through accessibility APIs. When you use the ask tool, you'll receive a confirmation that the message was sent, but you'll need to check the Claude Desktop window directly to see the response.

Workarounds

1. Use Claude's API: For programmatic access to responses, consider using Claude's API directly instead of desktop automation
2. Manual verification: After sending a prompt, manually check the Claude Desktop window for the response
3. One-way automation: Use this tool for scenarios where you only need to send prompts without reading responses

Claude Commands Integration

Claude Commands allow you to create reusable workflows that combine MCP tools. This project works seamlessly with Claude Commands to enable powerful automation.

Example: Code Peer Review Command

We've included an example Claude Command that demonstrates how to use MCP Claude Desktop for automated code reviews. The command uses git to analyze recent changes and sends them to Claude Desktop for peer review feedback.

Setup

1. Copy the example command to your Claude Commands directory:

   cp examples/claude-peer-review.md ~/.claude/commands/
   

2. The command will be available in Claude Code as /claude-peer-review

Usage

The peer review command accepts up to 3 arguments:

• description: What changes to review (e.g., "authentication fix")
• polling_interval: How often to check for response (default: 1.5s)
• timeout: Maximum wait time for response (default: 30s)

Examples:

# Review most recent commit with defaults
/claude-peer-review

# Review with description
/claude-peer-review "bug fix for user login"

# Custom polling interval (2 seconds)
/claude-peer-review "API update" 2

# Custom timeout for complex reviews (2 minutes)
/claude-peer-review "major refactor" 1.5 120

How It Works

1. Git Integration: The command automatically fetches:

   • Current git status
   • Recent commit statistics
   • Full diff of changes
   • Current branch name

2. Claude Desktop Review: Sends the changes to Claude Desktop with specific review questions:

   • Code appropriateness and implementation quality
   • Security concerns or potential bugs
   • Code quality and best practices
   • Suggestions for improvements

3. Response Handling: Uses the MCP server's polling mechanism to wait for Claude's response

4. Summary Generation: Provides a structured summary of:

   • Changes reviewed
   • Claude's feedback
   • Actions taken based on feedback
   • Final review status

Creating Your Own Commands

You can create custom Claude Commands that leverage MCP Claude Desktop. Commands should:

1. Include the tools in the frontmatter:

   ---
   allowed-tools: mcp__claude-desktop__ask, mcp__claude-desktop__get_conversations
   ---
   

2. Use the MCP tools with appropriate parameters:

   mcp__claude-desktop__ask
   prompt: "Your prompt here"
   timeout: 60
   pollingInterval: 2
   

3. Handle timeouts gracefully and suggest longer timeouts for complex queries

See the example command for a complete implementation.

Development

Running in Development Mode

npm run dev

Running Tests

npm test

Linting

npm run lint

Type Checking

npm run typecheck

API

Tools

ask

Send a prompt to Claude Desktop and get a response.

Parameters:

• prompt (string, required): The prompt to send
• conversationId (string, optional): Continue a specific conversation
• timeout (number, optional): Response timeout in seconds
  • Default: 30 seconds
  • Minimum: 1 second
  • Maximum: 300 seconds (5 minutes)
• pollingInterval (number, optional): How often to check for response in seconds
  • Default: 1.5 seconds
  • Minimum: 0.5 seconds
  • Maximum: 10 seconds

Response:

String containing Claude's response

get_conversations

Get a list of available conversations in Claude Desktop.

Parameters: None

Response:

{
  conversations: string[];
  timestamp: string;
}

Architecture

The MCP server uses AppleScript to communicate with Claude Desktop:

1. Claude Code sends a prompt via MCP
2. AppleScript activates Claude Desktop and creates a new conversation
3. The prompt is typed into Claude Desktop
4. The server polls Claude Desktop for the response
5. Once a response is detected, it's parsed and returned to Claude Code

Troubleshooting

Common Issues

1. "AppleScript execution failed"

   • Ensure Claude Desktop is installed and running
   • Check accessibility permissions
   • Try running the server with higher log level: LOG_LEVEL=3

2. "Response timed out"

   • Increase the timeout parameter: timeout: 60 (60 seconds)
   • For complex queries, use longer timeouts: timeout: 120 (2 minutes)
   • Reduce polling interval for faster detection: pollingInterval: 0.5
   • Check if Claude Desktop is responding normally
   • Ensure the system isn't under heavy load

3. "Permission denied"

   • Grant accessibility permissions to your terminal
   • Run the build command with proper permissions

4. MCP Server Crashes After Sending Requests If the MCP server crashes after handling requests, you can:

   • Disable response polling (recommended for stability):

     export SKIP_CLAUDE_POLLING=true
     

     This will send the message to Claude Desktop but won't try to read the response.

   • Enable debug logging to see what's happening:

     export LOG_LEVEL=3
     

   • Check stderr output - All logs are now written to stderr to avoid interfering with the MCP protocol on stdout.

Known Limitations with Response Polling

Response polling can occasionally cause instability due to:

• Extended polling duration (30 seconds default)
• Complex UI element reading from Electron apps
• Timing issues with Claude's response generation

Consider using SKIP_CLAUDE_POLLING=true for more reliable operation if you don't need response reading.

Contributing

We welcome contributions to MCP Claude Desktop! Whether you're fixing bugs, adding features, or improving documentation, your help is appreciated.

Getting Started

1. Fork the repository
2. Clone your fork:

   git clone https://github.com/YOUR_USERNAME/mcp-claude-desktop
   cd mcp-claude-desktop
   

3. Install dependencies:

   npm install
   

4. Create a new branch:

   git checkout -b feature/your-feature-name
   

Development Workflow

1. Make your changes
2. Run tests to ensure everything works:

   npm test
   

3. Run linting to maintain code quality:

   npm run lint
   

4. Run type checking:

   npm run typecheck
   

5. Build the project:

   npm run build
   

Code Style Guidelines

• Use TypeScript for all source code
• Follow the existing code style (enforced by ESLint)
• Write meaningful commit messages
• Add tests for new features
• Update documentation as needed

Submitting Changes

1. Commit your changes with a descriptive message:

   git commit -m "feat: add support for conversation history"
   

2. Push to your fork:

   git push origin feature/your-feature-name
   

3. Create a Pull Request on GitHub

Pull Request Guidelines

• Provide a clear description of the changes
• Reference any related issues
• Ensure all tests pass
• Update README if adding new features
• Be responsive to code review feedback

Reporting Issues

• Use GitHub Issues to report bugs
• Include macOS version and Node.js version
• Provide steps to reproduce the issue
• Include relevant error messages or logs

Feature Requests

• Open an issue to discuss new features
• Explain the use case and benefits
• Be open to feedback and alternative approaches

License

MIT