Skip to main content
21nauts
Back to Blog
MCPClaude DesktopSetup

Setting Up MCP with Claude Desktop

Complete configuration guide for integrating MCP servers with Claude Desktop. Learn installation, configuration, and troubleshooting tips for creating powerful AI-assisted workflows.

January 5, 2025
10 min read
21nauts Team

Setting Up MCP with Claude Desktop

Claude Desktop provides native support for the Model Context Protocol (MCP), enabling you to extend Claude's capabilities with custom tools, data sources, and workflows. This guide walks you through the complete setup process.

Prerequisites

Before starting, ensure you have:

  • Claude Desktop installed on your system
  • Basic understanding of JSON configuration
  • MCP server ready to connect (or use existing servers)

Installing Claude Desktop

Download and Installation

  1. Visit claude.ai/download
  2. Download the appropriate version for your operating system:
    • macOS: Claude Desktop.dmg
    • Windows: Claude Desktop Setup.exe
  3. Run the installer and follow the setup wizard

Initial Setup

After installation:

  1. Launch Claude Desktop
  2. Sign in with your Anthropic account
  3. Complete the initial onboarding

MCP Configuration

Configuration File Location

Claude Desktop reads MCP configuration from a JSON file located at:

macOS

~/Library/Application Support/Claude/claude_desktop_config.json

Windows

%APPDATA%\Claude\claude_desktop_config.json

Basic Configuration Structure

Create or edit the configuration file with this structure:

{
  "mcpServers": {
    "server-name": {
      "command": "command-to-run-server",
      "args": ["argument1", "argument2"],
      "env": {
        "ENVIRONMENT_VARIABLE": "value"
      }
    }
  }
}
JSON

Configuring Built-in Servers

Filesystem Server

Access local files and directories:

{
  "mcpServers": {
    "filesystem": {
      "command": "npx",
      "args": [
        "-y",
        "@modelcontextprotocol/server-filesystem",
        "/path/to/allowed/directory"
      ]
    }
  }
}
JSON

Capabilities:

  • Read file contents
  • List directory contents
  • Search for files
  • Get file metadata

Git Server

Interact with Git repositories:

{
  "mcpServers": {
    "git": {
      "command": "npx",
      "args": [
        "-y",
        "@modelcontextprotocol/server-git",
        "--repository",
        "/path/to/git/repository"
      ]
    }
  }
}
JSON

Capabilities:

  • View commit history
  • Show file changes
  • Create branches
  • Manage repositories

GitHub Server

Access GitHub repositories and issues:

{
  "mcpServers": {
    "github": {
      "command": "npx",
      "args": [
        "-y",
        "@modelcontextprotocol/server-github"
      ],
      "env": {
        "GITHUB_PERSONAL_ACCESS_TOKEN": "your-github-token"
      }
    }
  }
}
JSON

Capabilities:

  • Search repositories and issues
  • Create and manage issues
  • Access repository contents
  • View pull requests

Custom Server Configuration

Python Server Example

{
  "mcpServers": {
    "my-python-server": {
      "command": "python",
      "args": ["/path/to/your/server.py"],
      "env": {
        "API_KEY": "your-api-key",
        "DEBUG": "false"
      }
    }
  }
}
JSON

Node.js Server Example

{
  "mcpServers": {
    "my-node-server": {
      "command": "node",
      "args": ["/path/to/your/server.js"],
      "env": {
        "NODE_ENV": "production",
        "PORT": "3000"
      }
    }
  }
}
JSON

Executable Server Example

{
  "mcpServers": {
    "my-executable": {
      "command": "/path/to/your/executable",
      "args": ["--config", "/path/to/config.json"],
      "env": {
        "LOG_LEVEL": "info"
      }
    }
  }
}
JSON

Complete Configuration Examples

Development Setup

{
  "mcpServers": {
    "filesystem": {
      "command": "npx",
      "args": [
        "-y",
        "@modelcontextprotocol/server-filesystem",
        "/Users/username/projects"
      ]
    },
    "git": {
      "command": "npx",
      "args": [
        "-y",
        "@modelcontextprotocol/server-git",
        "--repository",
        "/Users/username/projects/my-repo"
      ]
    },
    "github": {
      "command": "npx",
      "args": [
        "-y",
        "@modelcontextprotocol/server-github"
      ],
      "env": {
        "GITHUB_PERSONAL_ACCESS_TOKEN": "ghp_xxxxxxxxxxxx"
      }
    }
  }
}
JSON

Data Analysis Setup

{
  "mcpServers": {
    "filesystem": {
      "command": "npx",
      "args": [
        "-y",
        "@modelcontextprotocol/server-filesystem",
        "/Users/username/data"
      ]
    },
    "sqlite": {
      "command": "npx",
      "args": [
        "-y",
        "@modelcontextprotocol/server-sqlite",
        "/path/to/database.db"
      ]
    },
    "web-search": {
      "command": "npx",
      "args": [
        "-y",
        "@modelcontextprotocol/server-brave-search"
      ],
      "env": {
        "BRAVE_API_KEY": "your-brave-api-key"
      }
    }
  }
}
JSON

Testing Your Configuration

Verify Configuration

  1. Save your configuration file
  2. Restart Claude Desktop completely
  3. Start a new conversation
  4. Test MCP functionality with commands like:
    • "List files in my project directory"
    • "Show me the latest commits"
    • "Search for issues in my repository"

Check Server Status

Claude Desktop provides feedback about MCP servers:

  • Green dot: Server connected successfully
  • Red dot: Server failed to connect
  • Orange dot: Server starting up

Debug Connection Issues

If servers fail to connect:

  1. Check file paths: Ensure all paths are correct and accessible
  2. Verify commands: Make sure commands are installed and executable
  3. Review environment variables: Check that required API keys are set
  4. Check logs: Look for error messages in Claude Desktop

Common Configuration Patterns

Environment-Specific Configs

Use environment variables for different setups:

{
  "mcpServers": {
    "api-server": {
      "command": "node",
      "args": ["server.js"],
      "env": {
        "NODE_ENV": "development",
        "API_BASE_URL": "http://localhost:3000",
        "DEBUG": "true"
      }
    }
  }
}
JSON

Multiple Server Instances

Run multiple instances of the same server type:

{
  "mcpServers": {
    "project-a-files": {
      "command": "npx",
      "args": [
        "-y",
        "@modelcontextprotocol/server-filesystem",
        "/path/to/project-a"
      ]
    },
    "project-b-files": {
      "command": "npx",
      "args": [
        "-y",
        "@modelcontextprotocol/server-filesystem",
        "/path/to/project-b"
      ]
    }
  }
}
JSON

Conditional Server Loading

Use shell scripts for conditional server loading:

{
  "mcpServers": {
    "conditional-server": {
      "command": "bash",
      "args": ["-c", "if [ -f /path/to/server ]; then /path/to/server; fi"]
    }
  }
}
JSON

Security Considerations

API Key Management

  • Never commit API keys to version control
  • Use environment files for local development
  • Rotate keys regularly for production use
  • Limit permissions to minimum required scope

File System Access

  • Restrict directory access to only necessary paths
  • Use absolute paths to avoid confusion
  • Set proper permissions on configuration files
  • Regular security audits of accessible directories

Network Security

  • Use HTTPS for all external connections
  • Validate certificates for secure connections
  • Implement rate limiting where appropriate
  • Monitor network traffic for suspicious activity

Troubleshooting

Common Issues

Server Won't Start

Problem: Red dot next to server name

Solutions:

  1. Check command path and arguments
  2. Verify environment variables
  3. Ensure dependencies are installed
  4. Check file permissions

Server Connects But No Functionality

Problem: Green dot but tools don't work

Solutions:

  1. Verify server implements required capabilities
  2. Check server logs for errors
  3. Test server independently
  4. Review server documentation

Performance Issues

Problem: Slow responses or timeouts

Solutions:

  1. Optimize server implementation
  2. Add caching where appropriate
  3. Reduce data transfer size
  4. Check network connectivity

Getting Help

If you encounter issues:

  1. Check documentation for your specific server
  2. Review Claude Desktop logs for error messages
  3. Test servers independently outside of Claude Desktop
  4. Contact support with specific error details

Advanced Configuration

Custom Server Discovery

Implement dynamic server discovery:

{
  "mcpServers": {
    "dynamic-server": {
      "command": "python",
      "args": ["discover_servers.py"],
      "env": {
        "SERVER_DISCOVERY_PATH": "/path/to/servers"
      }
    }
  }
}
JSON

Load Balancing

Distribute load across multiple server instances:

{
  "mcpServers": {
    "load-balanced-server-1": {
      "command": "node",
      "args": ["server.js", "--instance", "1"]
    },
    "load-balanced-server-2": {
      "command": "node",
      "args": ["server.js", "--instance", "2"]
    }
  }
}
JSON

Next Steps

Once you have MCP configured with Claude Desktop:

  1. Explore capabilities of your connected servers
  2. Build custom workflows using multiple servers
  3. Create your own servers for specific use cases
  4. Share configurations with your team
  5. Monitor performance and optimize as needed

Claude Desktop's MCP integration opens up unlimited possibilities for extending AI capabilities. With proper configuration and security practices, you can create powerful, customized AI workflows tailored to your specific needs.

Ready to build custom MCP servers? Check out our development guides for creating servers in Python and TypeScript.