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

# Claude Desktop Integration

> Configure Claude Desktop to use the MarkItDown MCP server for document conversion

Claude Desktop supports the Model Context Protocol, allowing it to use external tools like the MarkItDown MCP server. This guide shows you how to configure Claude Desktop to convert documents to Markdown during conversations.

## Overview

When integrated with Claude Desktop, the MarkItDown MCP server enables Claude to:

* Convert documents from URLs or local files to Markdown
* Analyze document content and answer questions about it
* Extract information from various file formats
* Process documents as part of natural conversations

<Info>
  It is recommended to use the Docker image when running the MCP server for Claude Desktop. This provides isolation and includes all necessary dependencies.
</Info>

## Prerequisites

* Claude Desktop installed on your system
* Docker installed (recommended) or markitdown-mcp via pip
* For Docker: Build the markitdown-mcp image (see [Installation](/integrations/mcp/installation))

## Configuration File Location

Claude Desktop reads MCP server configurations from a JSON file. The location varies by operating system:

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

For detailed instructions on finding this file, see the [MCP quickstart guide](https://modelcontextprotocol.io/quickstart/user#for-claude-desktop-users).

## Basic Configuration (Docker)

Edit `claude_desktop_config.json` and add the following configuration:

```json theme={null}
{
  "mcpServers": {
    "markitdown": {
      "command": "docker",
      "args": [
        "run",
        "--rm",
        "-i",
        "markitdown-mcp:latest"
      ]
    }
  }
}
```

This configuration:

* Names the server "markitdown" (visible in Claude Desktop)
* Runs the Docker container in STDIO mode
* Uses `--rm` to automatically clean up the container after use
* Uses `-i` for interactive mode (required for STDIO)

## Configuration with Local File Access

To allow Claude to access local files, mount a directory into the container:

```json theme={null}
{
  "mcpServers": {
    "markitdown": {
      "command": "docker",
      "args": [
        "run",
        "--rm",
        "-i",
        "-v",
        "/home/user/Documents:/workdir",
        "markitdown-mcp:latest"
      ]
    }
  }
}
```

<Note>
  Replace `/home/user/Documents` with the actual path to the directory you want to access. On Windows, use Windows-style paths like `C:\\Users\\YourName\\Documents`.
</Note>

### How It Works

* Files in `/home/user/Documents` are mounted to `/workdir` in the container
* To reference a file, use the path inside the container: `file:///workdir/filename.pdf`
* You can mount multiple directories by adding more `-v` arguments

### Example: Multiple Mounts

```json theme={null}
{
  "mcpServers": {
    "markitdown": {
      "command": "docker",
      "args": [
        "run",
        "--rm",
        "-i",
        "-v",
        "/home/user/Documents:/documents",
        "-v",
        "/home/user/Downloads:/downloads",
        "markitdown-mcp:latest"
      ]
    }
  }
}
```

## Configuration with pip Installation

If you installed markitdown-mcp via pip instead of Docker:

```json theme={null}
{
  "mcpServers": {
    "markitdown": {
      "command": "markitdown-mcp",
      "args": []
    }
  }
}
```

<Warning>
  When using pip installation, ensure markitdown-mcp is in your PATH and accessible from the user running Claude Desktop.
</Warning>

### With Plugins Enabled

```json theme={null}
{
  "mcpServers": {
    "markitdown": {
      "command": "markitdown-mcp",
      "args": [],
      "env": {
        "MARKITDOWN_ENABLE_PLUGINS": "true"
      }
    }
  }
}
```

## Enabling Plugins

To enable optional MarkItDown plugins, set the `MARKITDOWN_ENABLE_PLUGINS` environment variable:

```json theme={null}
{
  "mcpServers": {
    "markitdown": {
      "command": "docker",
      "args": [
        "run",
        "--rm",
        "-i",
        "-e",
        "MARKITDOWN_ENABLE_PLUGINS=true",
        "markitdown-mcp:latest"
      ]
    }
  }
}
```

<Info>
  The Docker image has plugins enabled by default. This configuration is only needed if you want to explicitly control the setting.
</Info>

## Applying Configuration Changes

After editing `claude_desktop_config.json`:

1. Save the file
2. Completely quit Claude Desktop (not just close the window)
3. Restart Claude Desktop
4. The MarkItDown server should now be available

## Using MarkItDown in Claude

Once configured, you can ask Claude to convert documents:

### Example Prompts

**Converting from URL:**

> "Can you convert this PDF to markdown? [https://example.com/document.pdf](https://example.com/document.pdf)"

**Converting local file:**

> "Please convert /workdir/report.docx to markdown and summarize it"

**Analyzing content:**

> "Convert /workdir/sales.xlsx to markdown and tell me the total revenue"

Claude will automatically:

1. Detect that it needs to use the `convert_to_markdown` tool
2. Call the MCP server with the appropriate URI
3. Receive the Markdown content
4. Process and respond based on your request

## Verifying the Integration

To verify the MCP server is working:

1. Open Claude Desktop
2. Look for a 🔌 (plug) icon or "Tools" indicator in the interface
3. Ask Claude: "What MCP tools do you have access to?"
4. Claude should mention the `convert_to_markdown` tool from the markitdown server

## Troubleshooting

### Server Not Showing Up

* Verify the JSON syntax is correct (use a JSON validator)
* Check that Docker is running (for Docker-based configs)
* Ensure the image name matches: `markitdown-mcp:latest`
* Restart Claude Desktop completely

### File Access Errors

* Verify the mount path exists and is readable
* Check that file paths use the container path (e.g., `/workdir/...`)
* Ensure the Docker container has permission to access the mounted directory

### Permission Issues

* On Linux/macOS, you may need to adjust the USERID and GROUPID in the Docker build:
  ```bash theme={null}
  docker build --build-arg USERID=$(id -u) --build-arg GROUPID=$(id -g) -t markitdown-mcp:latest .
  ```

### Debugging

To debug issues:

1. Test the server independently using [mcpinspector](/integrations/mcp/usage#debugging-with-mcpinspector)
2. Check Claude Desktop logs (location varies by OS)
3. Test the Docker command manually in a terminal
4. Verify the configuration file has valid JSON syntax

## Advanced Configuration

### Custom Image Tag

If you built the image with a different tag:

```json theme={null}
{
  "mcpServers": {
    "markitdown": {
      "command": "docker",
      "args": [
        "run",
        "--rm",
        "-i",
        "my-custom-markitdown:v1.0"
      ]
    }
  }
}
```

### Multiple MCP Servers

You can configure multiple MCP servers in the same file:

```json theme={null}
{
  "mcpServers": {
    "markitdown": {
      "command": "docker",
      "args": ["run", "--rm", "-i", "markitdown-mcp:latest"]
    },
    "another-server": {
      "command": "other-mcp-server",
      "args": []
    }
  }
}
```

## Security Considerations

<Warning>
  Be careful when mounting directories. The MCP server will have read access to all files in mounted directories.
</Warning>

### Best Practices

1. **Mount only necessary directories**: Don't mount your entire home directory
2. **Use read-only mounts** when possible:
   ```json theme={null}
   "-v", "/path/to/dir:/workdir:ro"
   ```
3. **Avoid mounting sensitive directories**: Don't mount directories containing credentials or private keys
4. **Review file paths**: Always verify file paths before asking Claude to process them

## Next Steps

<CardGroup cols={2}>
  <Card title="Usage Guide" icon="book" href="/integrations/mcp/usage">
    Learn more about the MCP server features
  </Card>

  <Card title="Supported Formats" icon="file" href="/formats/overview">
    See all document formats supported by MarkItDown
  </Card>
</CardGroup>