Skip to main content
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.
Platform Support: macOS and Windows Transport Mode: Stdio (local process management) Note: For remote HTTP servers, use Claude Code instead

​
Configuration File Location

Claude Desktop stores its MCP server configuration in: 
~/Library/Application Support/Claude/claude_desktop_config.json

​
Local (Stdio) Setup

For local development with the server running on your machine: Step 1: Ensure server is installed 
cd ibmi-mcp-server
npm install && npm run build
npm link
Step 2: Edit configuration file Edit claude_desktop_config.json: 
{
  "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"
      }
    }
  }
}
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
Step 3: Restart Claude Desktop Close and reopen Claude Desktop to load the new configuration.
Remote Servers: Claude Desktop only supports local stdio servers. For connecting to remote MCP servers via HTTP, use Claude Code instead, which supports HTTP transport.

​
Environment Variable Expansion

Claude Desktop supports environment variable expansion for secure credential management: 
{
  "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): 
# 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”

​
Troubleshooting

Symptoms: MCP server doesn’t show up in Claude DesktopSolutions:
  • 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
Symptoms: Connection refused or 401 UnauthorizedSolutions:
  • 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
Symptoms: Server connects but no tools availableSolutions:
  • 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
Symptoms: Server starts but can’t connect to IBM iSolutions:
  • 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

​
Advanced Configuration

​
Multiple IBM i Systems

Configure multiple server instances for different IBM i systems: 
{
  "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: 
{
  "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

Configuration Reference

Explore all environment variables and settings

SQL Tools

Learn how to create custom SQL tools

Authentication

Set up secure IBM i HTTP authentication

Other Clients

Explore other MCP-compatible clients

​
Additional Resources