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

# Claude Desktop

> Configure IBM i MCP Server with Claude Desktop app for macOS and Windows

Claude Desktop is the official desktop application for Claude, available for macOS and Windows. It provides a rich interface for interacting with Claude while supporting MCP servers for extended capabilities.

<Note>
  **Platform Support**: macOS and Windows
  **Transport Mode**: Stdio (local process management)
  **Note**: For remote HTTP servers, use Claude Code instead
</Note>

## Configuration File Location

Claude Desktop stores its MCP server configuration in:

<Tabs>
  <Tab title="macOS">
    ```bash theme={null}
    ~/Library/Application Support/Claude/claude_desktop_config.json
    ```
  </Tab>

  <Tab title="Windows">
    ```bash theme={null}
    %APPDATA%\Claude\claude_desktop_config.json
    ```
  </Tab>
</Tabs>

## Local (Stdio) Setup

For local development with the server running on your machine:

**Step 1: Ensure server is installed**

```bash theme={null}
cd ibmi-mcp-server
npm install && npm run build
npm link
```

**Step 2: Edit configuration file**

Edit `claude_desktop_config.json`:

```json theme={null}
{
  "mcpServers": {
    "ibmi-mcp": {
      "command": "npx",
      "args": ["-y", "@ibm/ibmi-mcp-server@latest", "--tools", "/absolute/path/to/tools"],
      "env": {
        "DB2i_HOST": "your-ibmi-host.com",
        "DB2i_USER": "your-username",
        "DB2i_PASS": "your-password",
        "DB2i_PORT": "8076",
        "MCP_TRANSPORT_TYPE": "stdio",
        "NODE_OPTIONS": "--no-deprecation"
      }
    }
  }
}
```

<Warning>
  **Important**:

  * The `--tools` path must be an **absolute path**
  * Replace credentials with your actual IBM i system details
  * User profile must have appropriate database authorities
</Warning>

**Step 3: Restart Claude Desktop**

Close and reopen Claude Desktop to load the new configuration.

<Info>
  **Remote Servers**: Claude Desktop only supports local stdio servers. For connecting to remote MCP servers via HTTP, use [Claude Code](/clients/claude-code#remote-http-setup) instead, which supports HTTP transport.
</Info>

## Environment Variable Expansion

Claude Desktop supports environment variable expansion for secure credential management:

```json theme={null}
{
  "mcpServers": {
    "ibmi-mcp": {
      "command": "npx",
      "args": ["-y", "@ibm/ibmi-mcp-server@latest", "--tools", "${IBMI_TOOLS_PATH}"],
      "env": {
        "DB2i_HOST": "${DB2i_HOST}",
        "DB2i_USER": "${DB2i_USER}",
        "DB2i_PASS": "${DB2i_PASS}",
        "DB2i_PORT": "${DB2i_PORT:-8076}",
        "MCP_TRANSPORT_TYPE": "stdio"
      }
    }
  }
}
```

**Supported syntax:**

* `${VAR}` - Expands to the value of environment variable `VAR`
* `${VAR:-default}` - Expands to `VAR` if set, otherwise uses `default`

**Set environment variables** (before launching Claude Desktop):

```bash theme={null}
# macOS/Linux
export DB2i_HOST=your-ibmi-host.com
export DB2i_USER=your-username
export DB2i_PASS=your-password
export IBMI_TOOLS_PATH=/absolute/path/to/tools

# Windows (PowerShell)
$env:DB2i_HOST="your-ibmi-host.com"
$env:DB2i_USER="your-username"
$env:DB2i_PASS="your-password"
$env:IBMI_TOOLS_PATH="C:\path\to\tools"
```

## Testing the Connection

After configuring and restarting Claude Desktop:

1. **Check MCP status**: Look for the MCP icon (plug symbol) in Claude Desktop
2. **List available tools**: Ask Claude "What tools do you have available?"
3. **Test a tool**: Try "Show me the system status of my IBM i"

<Success>
  If configured correctly, Claude should list the IBM i MCP tools and be able to execute them.
</Success>

## Troubleshooting

<AccordionGroup>
  <Accordion title="Server Not Appearing">
    **Symptoms**: MCP server doesn't show up in Claude Desktop

    **Solutions**:

    * Verify JSON syntax in `claude_desktop_config.json`
    * Check that `npx -y @ibm/ibmi-mcp-server@latest` works from terminal
    * Ensure absolute paths are used for `--tools`
    * Restart Claude Desktop completely (Cmd+Q / Alt+F4, then relaunch)
    * Check Claude Desktop logs for errors
  </Accordion>

  <Accordion title="Authentication Failed (Remote)">
    **Symptoms**: Connection refused or 401 Unauthorized

    **Solutions**:

    * Verify server is running: `curl http://localhost:3010/mcp`
    * Check token is valid: `echo $IBMI_MCP_ACCESS_TOKEN`
    * Ensure token hasn't expired (default: 1 hour)
    * Confirm `MCP_AUTH_MODE=ibmi` and `IBMI_HTTP_AUTH_ENABLED=true`
    * Get a fresh token: `node get-access-token.js --verbose`
  </Accordion>

  <Accordion title="Tools Not Loading">
    **Symptoms**: Server connects but no tools available

    **Solutions**:

    * Verify tools path exists and is absolute
    * Check YAML files are valid: `npm run validate -- --config tools`
    * Ensure IBM i credentials are correct
    * Verify Mapepire is running on IBM i: `sc check mapepire`
    * Check server logs for tool loading errors
  </Accordion>

  <Accordion title="Connection to IBM i Failed">
    **Symptoms**: Server starts but can't connect to IBM i

    **Solutions**:

    * Test IBM i connectivity: `ping your-ibmi-host`
    * Verify Mapepire is running: `netstat -an | grep 8076`
    * Check firewall allows port 8076
    * Verify credentials with: `node get-access-token.js --verbose`
    * Ensure user has database authorities
  </Accordion>
</AccordionGroup>

## Advanced Configuration

### Multiple IBM i Systems

Configure multiple server instances for different IBM i systems:

```json theme={null}
{
  "mcpServers": {
    "ibmi-dev": {
      "command": "npx",
      "args": ["-y", "@ibm/ibmi-mcp-server@latest", "--tools", "/path/to/dev-tools"],
      "env": {
        "DB2i_HOST": "dev-ibmi.company.com",
        "DB2i_USER": "DEVUSER",
        "DB2i_PASS": "devpass",
        "MCP_TRANSPORT_TYPE": "stdio"
      }
    },
    "ibmi-prod": {
      "command": "npx",
      "args": ["-y", "@ibm/ibmi-mcp-server@latest", "--tools", "/path/to/prod-tools"],
      "env": {
        "DB2i_HOST": "prod-ibmi.company.com",
        "DB2i_USER": "PRODUSER",
        "DB2i_PASS": "${PROD_PASSWORD}",
        "MCP_TRANSPORT_TYPE": "stdio"
      }
    }
  }
}
```

### Custom Tool Sets

Load specific toolsets instead of all tools:

```json theme={null}
{
  "mcpServers": {
    "ibmi-mcp": {
      "command": "npx",
      "args": [
        "-y",
        "@ibm/ibmi-mcp-server@latest",
        "--tools", "/absolute/path/to/tools",
        "--toolsets", "performance,security"
      ],
      "env": {
        "DB2i_HOST": "your-ibmi-host.com",
        "DB2i_USER": "your-username",
        "DB2i_PASS": "your-password",
        "MCP_TRANSPORT_TYPE": "stdio"
      }
    }
  }
}
```

## Next Steps

<CardGroup cols={2}>
  <Card title="Configuration Reference" icon="gear" href="/configuration">
    Explore all environment variables and settings
  </Card>

  <Card title="SQL Tools" icon="database" href="/sql-tools/overview">
    Learn how to create custom SQL tools
  </Card>

  <Card title="Authentication" icon="lock" href="/configuration#ibm-i-authentication-settings">
    Set up secure IBM i HTTP authentication
  </Card>

  <Card title="Other Clients" icon="grid" href="/clients/overview">
    Explore other MCP-compatible clients
  </Card>
</CardGroup>

## Additional Resources

* [Claude Desktop Documentation](https://modelcontextprotocol.io/quickstart/user)
* [MCP Specification](https://modelcontextprotocol.io/specification)
* [IBM i MCP Quick Start](/quickstart)
* [Troubleshooting Guide](/clients/overview#troubleshooting)