> ## Documentation Index
> Fetch the complete documentation index at: https://docs.morphllm.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Morph MCP Server

> Add fast AI code editing to Claude Desktop, Cursor, VS Code and more with Morph Apply API

# Morph MCP Server

Connect your favorite AI tools to Morph's blazing-fast file editing via Model Context Protocol.

## What You Get

* **Lightning Fast**: 10,500+ tokens/sec code editing
* **High Accuracy**: 98% success rate on code transformations
* **Flexible Tools**: Choose between edit-only or full filesystem access
* **Universal**: Works with Claude Desktop, Cursor, VS Code, and any MCP-compatible client

## Available Tools

All tools are enabled by default. Use `DISABLED_TOOLS` to selectively disable specific tools.

* `edit_file` - Lightning-fast code edits via Morph Apply
* `codebase_search` - Semantic code search via Warp-Grep
* `github_codebase_search` - Search GitHub repositories

## Search Model (Warp-Grep)

Use Morph's Warp-Grep for fast, local code search alongside your MCP setup. See the minimal SDK guide: [/sdk/components/fast-grep](/sdk/components/fast-grep).

## Quick Start

<Tabs>
  <Tab title="Claude Code">
    Add to your Claude Code config file:

    **macOS**: `~/.claude/settings.json`
    **Windows**: `%USERPROFILE%\.claude\settings.json`

    ```json theme={null}
    {
      "mcpServers": {
        "filesystem-with-morph": {
          "command": "npx",
          "args": [
            "@morphllm/morphmcp",
            "/Users/your-username/"
          ],
          "env": {
            "MORPH_API_KEY": "YOUR_API_KEY"
          }
        }
      }
    }
    ```

    **Restart Claude Code** completely to load the new configuration.
  </Tab>

  <Tab title="Codex">
    Add to your Codex MCP config file:

    **Location**: `~/.codex/mcp.json`

    ```json theme={null}
    {
      "mcpServers": {
        "filesystem-with-morph": {
          "command": "npx",
          "args": [
            "@morphllm/morphmcp",
            "/Users/your-username/"
          ],
          "env": {
            "MORPH_API_KEY": "YOUR_API_KEY"
          }
        }
      }
    }
    ```

    **Restart Codex** to load the new configuration.
  </Tab>

  <Tab title="Cursor">
    Add to your Cursor MCP config file:

    **Location**: `~/.cursor/mcp.json`

    ```json theme={null}
    {
      "mcpServers": {
        "filesystem-with-morph": {
          "command": "npx",
          "args": [
            "@morphllm/morphmcp",
            "/Users/your-username/"
          ],
          "env": {
            "MORPH_API_KEY": "YOUR_API_KEY"
          }
        }
      }
    }
    ```

    **Restart Cursor** to load the new configuration.
  </Tab>

  <Tab title="Claude Desktop">
    Add to your Claude Desktop config file:

    **macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json`
    **Windows**: `%APPDATA%/Claude/claude_desktop_config.json`

    ```json theme={null}
    {
      "mcpServers": {
        "filesystem-with-morph": {
          "command": "npx",
          "args": [
            "@morphllm/morphmcp",
            "/Users/your-username/"
          ],
          "env": {
            "MORPH_API_KEY": "YOUR_API_KEY"
          }
        }
      }
    }
    ```

    **Restart Claude Desktop** completely to load the new configuration.
  </Tab>

  <Tab title="Manual">
    Run the MCP server manually:

    ```bash theme={null}
    export MORPH_API_KEY="YOUR_API_KEY"
    export ALL_TOOLS="true"  # or "false" for edit-only mode
    npx @morphllm/morphmcp /Users/your-filepath/
    ```
  </Tab>
</Tabs>

## Installation Steps

### 1. Configure MCP Server

Choose your configuration based on your needs:

**Global Config (Workspace-Aware) - RECOMMENDED for cross-project use**:

```json theme={null}
{
  "mcpServers": {
    "filesystem-with-morph": {
      "command": "npx",
      "args": [
        "@morphllm/morphmcp"
      ],
      "env": {
        "MORPH_API_KEY": "YOUR_API_KEY",
        "ALL_TOOLS": "true"
      }
    }
  }
}
```

**Project-Specific Config**:

```json theme={null}
{
  "mcpServers": {
    "filesystem-with-morph": {
      "command": "npx",
      "args": [
        "@morphllm/morphmcp",
        "/Users/your-username/specific-project/"
      ],
      "env": {
        "MORPH_API_KEY": "YOUR_API_KEY",
        "ALL_TOOLS": "false"
      }
    }
  }
}
```

**Edit-Only Mode** (ALL\_TOOLS: "false"):

```json theme={null}
{
  "mcpServers": {
    "filesystem-with-morph": {
      "command": "npx",
      "args": [
        "@morphllm/morphmcp"
      ],
      "env": {
        "MORPH_API_KEY": "YOUR_API_KEY",
        "ALL_TOOLS": "false"
      }
    }
  }
}
```

### 2. Get API Key

Get your API key from the [dashboard](https://morphllm.com/api-keys) and replace `your-api-key-here` in the config.

### 3. Restart Your Client

Restart Claude Desktop, Cursor, or VS Code to load the new MCP server configuration.

## Workspace-Aware Global Config

The **workspace mode** is now **enabled by default** and solves the global vs project config inheritance issue by automatically detecting the current workspace root.

### How It Works

By default, the MCP server automatically:

1. **Automatic Detection**: Detects workspace root by looking for common indicators:
   * `.git` directories
   * `package.json`, `Cargo.toml`, `pyproject.toml`
   * `.vscode`, `.cursor` directories
   * And other common project files

2. **Dynamic Permissions**: Allowed directories update based on the current workspace context

3. **Fallback Safety**: If no workspace is detected, it falls back to the current directory

### Troubleshooting Global Config Issues

If your global MCP config isn't working:

**Problem**: "MCP server only works when configured per project"

**Solution**: Use the simplified global config (workspace mode is now default):

```json theme={null}
{
  "mcpServers": {
    "filesystem-with-morph": {
      "command": "npx",
      "args": ["@morphllm/morphmcp"],
      "env": {
        "MORPH_API_KEY": "YOUR_API_KEY",
        "ALL_TOOLS": "true"
      }
    }
  }
}
```

**Advanced**: To disable workspace mode (revert to legacy behavior):

```json theme={null}
{
  "env": {
    "MORPH_API_KEY": "YOUR_API_KEY",
    "ALL_TOOLS": "true",
    "ENABLE_WORKSPACE_MODE": "false"
  }
}
```

**Common Issues**:

* ❌ **Fixed paths**: `/Users/username/project` only works for that specific project
* ✅ **Workspace mode**: Automatically adapts to any project you open (now default)
* ✅ **Simplified config**: No need for `ENABLE_WORKSPACE_MODE=true` anymore
* ✅ **Proper inheritance**: Global config works across all projects by default

## Test Your Setup

Once configured, test that everything works:

1. **List Tools**: Ask your AI assistant: "What MCP tools are available?"
2. **Test Edit**: Try: "Edit this file to add a comment at the top"
3. **Check Access**: If using `ALL_TOOLS: "true"`, try: "List the files in this directory"

## Usage Examples

### Basic Code Editing

<CodeGroup>
  ```text Example Request theme={null}
  "Edit the file main.py to add error handling to the divide function"
  ```

  ```python Expected Result theme={null}
  # Original: def divide(a, b): return a / b
  # Updated:
  def divide(a, b):
      if b == 0:
          raise ValueError("Cannot divide by zero")
      return a / b
  ```
</CodeGroup>

### File Operations (ALL\_TOOLS: "true")

<CodeGroup>
  ```text Example Request theme={null}
  "Create a new file called utils.py with a helper function"
  ```

  ```python Expected Result theme={null}
  # New file: utils.py
  def format_output(data):
      """Format data for display"""
      return json.dumps(data, indent=2)
  ```
</CodeGroup>

### Project Refactoring

<CodeGroup>
  ```text Example Request theme={null}
  "Refactor the UserService class to use dependency injection"
  ```

  ```python Expected Result theme={null}
  # Before:
  class UserService:
      def __init__(self):
          self.db = Database()
          self.cache = Cache()

  # After:
  class UserService:
      def __init__(self, db: Database, cache: Cache):
          self.db = db
          self.cache = cache
  ```
</CodeGroup>

## Environment Variables

* **MORPH\_API\_KEY**: Your Morph API key (required)
* **ALL\_TOOLS**: Set to "true" for full filesystem access, "false" for edit-only mode
* **DISABLED\_TOOLS**: Comma-separated list of tools to disable (e.g. `"edit_file,codebase_search"`). Available tool names: `edit_file`, `codebase_search`, `github_codebase_search`. Tools not listed remain enabled.

## CLI Testing

Test the MCP server directly:

```bash theme={null}
# Install the package
npm install -g @morphllm/morphmcp

# Test edit-only mode
export MORPH_API_KEY="YOUR_API_KEY"
export ALL_TOOLS="false"
npx @morphllm/morphmcp /path/to/your/project/

# Test full access mode
export ALL_TOOLS="true"
npx @morphllm/morphmcp /path/to/your/project/
```

## Troubleshooting

<AccordionGroup>
  <Accordion title="Tools not showing up in client">
    1. Check that your client supports MCP servers
    2. Verify your config file syntax is correct (JSON must be valid)
    3. Restart your client completely (quit and reopen)
    4. Check client logs for MCP-related errors
    5. Verify the package can be installed: `npm install -g @morphllm/morphmcp`
    6. Try asking your AI: "What MCP tools are available?"
  </Accordion>

  <Accordion title="API key errors">
    1. Verify your API key is correct in the environment variables
    2. Ensure the key starts with 'sk-'
    3. Check that the key has the right permissions
    4. Get your API key from [morphllm.com](https://morphllm.com/dashboard/api-keys)
    5. Test the key with a direct API call
  </Accordion>

  <Accordion title="File access issues">
    1. Check that the path in the config is correct
    2. Verify you have read/write permissions to the directory
    3. Try with `ALL_TOOLS: "false"` first to test basic editing
    4. Check if the directory exists and is accessible
  </Accordion>

  <Accordion title="Package installation issues">
    1. Ensure Node.js and npm are installed
    2. Try installing globally: `npm install -g @morphllm/morphmcp`
    3. Check npm permissions
    4. Try running with `npx` instead of global install
  </Accordion>
</AccordionGroup>

## Best Practices

<CardGroup cols={2}>
  <Card title="Security" icon="shield">
    * Use `ALL_TOOLS: "false"` for untrusted environments
    * Limit the directory scope in your config
    * Regularly rotate your API keys
    * Monitor usage in your dashboard
  </Card>

  <Card title="Performance" icon="rocket">
    * Use specific file paths for faster operations
    * Break large refactoring into smaller steps
    * Monitor API usage and rate limits
    * Cache frequently used patterns
  </Card>
</CardGroup>

## Advanced Configuration

### Custom Directory Scope

Limit the MCP server to specific directories:

```json theme={null}
{
  "mcpServers": {
    "filesystem-with-morph": {
      "command": "npx",
      "args": [
        "@morphllm/morphmcp",
        "/Users/your-username/projects/specific-project/"
      ],
      "env": {
        "MORPH_API_KEY": "YOUR_API_KEY",
        "ALL_TOOLS": "false"
      }
    }
  }
}
```

### Multiple Configurations

Run different MCP servers for different projects:

```json theme={null}
{
  "mcpServers": {
    "morph-project-a": {
      "command": "npx",
      "args": ["@morphllm/morphmcp", "/path/to/project-a/"],
      "env": {
        "MORPH_API_KEY": "YOUR_API_KEY",
        "ALL_TOOLS": "false"
      }
    },
    "morph-project-b": {
      "command": "npx",
      "args": ["@morphllm/morphmcp", "/path/to/project-b/"],
      "env": {
        "MORPH_API_KEY": "YOUR_API_KEY",
        "ALL_TOOLS": "true"
      }
    }
  }
}
```

## Verify Your Setup

To confirm everything is working:

1. **Check Package**: Run `npx @morphllm/morphmcp --help` to verify installation
2. **Test Tools**: Ask your AI: "What MCP tools are available?" - should show tools based on your `ALL_TOOLS` setting
3. **Try Edit**: Test file editing with a simple change
4. **Check Access**: If using `ALL_TOOLS: "true"`, try listing directory contents

If all tests pass, you're ready to use fast AI code editing! 🎉

## Optimizing Agent Behavior

Add to your agent's config (`CLAUDE.md`, `.cursor/rules`, or `AGENTS.md`):

```markdown theme={null}
Fast Apply: IMPORTANT: Use `edit_file` over `str_replace` or full file writes. It works with partial code snippets—no need for full file content.
Warp Grep: warp-grep is a subagent that takes in a search string and tries to find relevant context. Best practice is to use it at the beginning of codebase explorations to fast track finding relevant files/lines. Do not use it to pin point keywords, but use it for broader semantic queries. "Find the XYZ flow", "How does XYZ work", "Where is XYZ handled?", "Where is <error message> coming from?"
```

## Support

* **Documentation**: [Morph Apply API Docs](https://docs.morphllm.com/api-reference/endpoint/apply)
* **MCP Protocol**: [Model Context Protocol](https://modelcontextprotocol.io/)
* **Get API Key**: [morphllm.com](https://morphllm.com/dashboard/api-keys)

<Note>
  **Need help?** Contact us at [morphllm.com](https://morphllm.com) or check our documentation for more details.
</Note>