Master Claude Desktop MCP server setup in 20 minutes. Complete config JSON tutorial with filesystem integration, troubleshooting, and proven solutions.
## TL;DR
This tutorial teaches you to configure MCP servers in Claude Desktop using JSON configuration files in 20 minutes. You'll learn config file location and structure, server setup syntax, and multi-server deployment. Build a complete development environment with filesystem, GitHub, and database integrations. Perfect for developers who want to extend Claude Desktop with local tool access.
**Key Points:**
- Config file location and JSON structure - create working MCP configurations
- Filesystem server setup - enable local file access in Claude
- Environment variables and API keys - secure credential management
- 20 minutes total with 5 hands-on configuration exercises
Master MCP server configuration in Claude Desktop with this comprehensive tutorial. By completion, you'll have multiple working MCP servers and understand JSON configuration patterns. This guide includes 5 practical examples, 10 code samples, and 3 real-world configurations.
> **Tutorial Requirements**
>
> **Prerequisites:** Basic JSON knowledge, Claude Desktop installed
> **Time Required:** 20 minutes active work
> **Tools Needed:** Text editor, npm/Node.js installed
> **Outcome:** Working MCP server configuration with filesystem access
## What You'll Learn
<!-- Section type: feature_grid -->
## Step-by-Step Tutorial
1. **Step 1: Locate Configuration Directory**
2. **Step 2: Create Basic Configuration**
3. **Step 3: Add Environment Variables**
4. **Step 4: Deploy Multiple Servers**
5. **Step 5: Validate and Test Configuration**
## Key Concepts Explained
Understanding these concepts ensures you can adapt this tutorial to your specific needs and troubleshoot issues effectively.
<!-- Section type: accordion -->
## Practical Examples
<!-- Section type: tabs -->
## Troubleshooting Guide
> **Common Issues and Solutions**
>
> **Issue 1: Cannot connect to MCP server**
> **Solution:** Validate JSON syntax with python -m json.tool. This fixes invalid JSON causing connection failures.
>
> **Issue 2: Server disconnected unexpectedly**
> **Solution:** Check Claude Desktop logs at ~/Library/Logs/Claude/. Missing dependencies cause 80% of disconnections.
>
> **Issue 3: Windows path errors**
> **Solution:** Use double backslashes or forward slashes. Escape sequences break Windows path parsing.
## Advanced Techniques
> **Professional Tips**
>
> **Performance Optimization:** Global npm installation reduces startup time by 3 seconds while maintaining functionality.
>
> **Security Best Practice:** Always use platform keychains for credentials. This approach prevents token exposure in configs.
>
> **Scalability Pattern:** For multiple projects, use separate configs. Switch configurations based on active project context.
## Validation and Testing
<!-- Section type: feature_grid -->
## Next Steps and Learning Path
## Quick Reference
**Tutorial Cheat Sheet - Essential commands and concepts:**
- **Primary Command**: `npx -y @modelcontextprotocol/server-filesystem /path` - Core command that enables filesystem access and produces directory listing
- **Configuration Pattern**: `{"mcpServers": {"name": {"command": "npx", "args": []}}}` - Standard configuration for MCP servers with required fields
- **Validation Check**: `python -m json.tool claude_desktop_config.json` - Verifies JSON syntax and confirms proper formatting
- **Troubleshooting**: `tail -f ~/Library/Logs/Claude/mcp*.log` - Monitors MCP server logs - target: zero errors
- **Performance Metric**: Server startup under 5 seconds - Measures initialization speed - target: <5s benchmark
- **Best Practice**: Use environment variables for all credentials - Professional standard for secure credential management
## Related Learning Resources
<!-- Section type: related_content -->
---
> **Tutorial Complete!**
>
> **Congratulations!** You've mastered MCP server configuration and can now extend Claude Desktop with local tools.
>
> **What you achieved:**
> - ✅ Created working MCP server configurations
> - ✅ Implemented secure credential management
> - ✅ Deployed multiple servers successfully
>
> **Ready for more?** Explore our [tutorials collection](/guides/tutorials) or join our [community](/community) to share your implementation and get help with advanced use cases.
*Last updated: September 2025 | Found this helpful? Share it with your team and explore more [Claude tutorials](/guides/tutorials).*
{
"userLevel": {
"file": "~/.claude/settings.json",
"location": "User settings",
"cliCommand": "claude mcp add --scope user --transport http server-name https://api.example.com/mcp"
},
"cliCommands": {
"list": "claude mcp list",
"remove": "claude mcp remove server-name",
"addHttp": "claude mcp add --transport http server-name https://api.example.com/mcp",
"addStdio": "claude mcp add --transport stdio server-name -- npx -y @package/server",
"addWithEnv": "claude mcp add --transport stdio server-name --env API_KEY=value -- npx -y @package/server"
},
"projectLevel": {
"file": ".mcp.json",
"example": {
"mcpServers": {
"github": {
"env": {
"GITHUB_TOKEN": "your-token"
},
"args": [
"-y",
"@anthropic-ai/mcp-server-github"
],
"command": "npx"
}
}
},
"location": "Project root"
}
}{
"jsonSyntax": "python -m json.tool claude_desktop_config.json",
"testInClaude": "Ask Claude: List files in my configured directory",
"logMonitoring": "tail -f ~/Library/Logs/Claude/mcp*.log"
}{
"configPath": {
"linux": "~/.config/claude/claude_desktop_config.json",
"macOS": "~/Library/Application Support/Claude/claude_desktop_config.json",
"windows": "%APPDATA%\\Claude\\claude_desktop_config.json"
},
"exampleBasic": {
"mcpServers": {
"filesystem": {
"args": [
"-y",
"@modelcontextprotocol/server-filesystem",
"/path/to/directory"
],
"command": "npx"
}
}
},
"exampleWithEnv": {
"mcpServers": {
"github": {
"env": {
"GITHUB_PERSONAL_ACCESS_TOKEN": "${GITHUB_PAT}"
},
"args": [
"-y",
"@modelcontextprotocol/server-github"
],
"command": "npx"
}
}
},
"exampleMultiServer": {
"mcpServers": {
"github": {
"args": [
"-y",
"@modelcontextprotocol/server-github"
],
"command": "npx"
},
"memory": {
"args": [
"-y",
"@modelcontextprotocol/server-memory"
],
"command": "npx"
},
"filesystem": {
"args": [
"-y",
"@modelcontextprotocol/server-filesystem",
"./projects"
],
"command": "npx"
}
}
}
}Cannot connect to MCP server
Validate JSON syntax with `python -m json.tool claude_desktop_config.json`. Invalid JSON causes connection failures. Check for missing commas, unclosed brackets, or syntax errors.
Server disconnected unexpectedly
Check Claude Desktop logs at `~/Library/Logs/Claude/` (macOS) or `%APPDATA%\Claude\logs\` (Windows). Missing dependencies cause 80% of disconnections. Install required packages: `npm install -g @modelcontextprotocol/server-package`.
Windows path errors in configuration
Use double backslashes (`\\`) or forward slashes (`/`) in Windows paths. Escape sequences break Windows path parsing. Example: Use `C:/Users/username/Documents` instead of `C:\Users\username\Documents`.
Environment variables not resolving
Verify environment variables are set in your shell session. Use `${VAR_NAME}` syntax in JSON config. For Windows, use `%VAR_NAME%` format. Test with `echo $VAR_NAME` (Unix) or `echo %VAR_NAME%` (Windows).
MCP servers not appearing in Claude Desktop
Restart Claude Desktop after configuration changes. Verify config file location matches your platform. Check file permissions allow Claude Desktop to read the config. Use Settings > Developer > Edit Config to verify file is being read.
Simple filesystem server setup for document access in Claude Desktop
{
"mcpServers": {
"filesystem": {
"command": "npx",
"args": ["-y", "@modelcontextprotocol/server-filesystem", "/Users/username/Documents"]
}
}
}GitHub integration with environment variable for secure token management
{
"mcpServers": {
"github": {
"command": "npx",
"args": ["-y", "@modelcontextprotocol/server-github"],
"env": {
"GITHUB_PERSONAL_ACCESS_TOKEN": "${GITHUB_PAT}"
}
}
}
}Combined filesystem, memory, and GitHub servers for full development workflow
{
"mcpServers": {
"filesystem": {
"command": "npx",
"args": ["-y", "@modelcontextprotocol/server-filesystem", "./projects"]
},
"memory": {
"command": "npx",
"args": ["-y", "@modelcontextprotocol/server-memory"]
},
"github": {
"command": "npx",
"args": ["-y", "@modelcontextprotocol/server-github"]
}
}
}PostgreSQL database server with connection string from environment variable
{
"mcpServers": {
"database": {
"command": "npx",
"args": ["-y", "@modelcontextprotocol/server-postgres"],
"env": {
"DATABASE_URL": "${POSTGRES_CONNECTION}"
}
}
}
}Command to validate JSON syntax and catch configuration errors before restarting Claude Desktop
python -m json.tool claude_desktop_config.jsonReal-time log monitoring to diagnose MCP server connection issues on macOS
tail -f ~/Library/Logs/Claude/mcp*.logAdd remote HTTP MCP server to Claude Code using CLI command
claude mcp add --transport http server-name https://api.example.com/mcpLoading reviews...
Official GitHub MCP server providing comprehensive GitHub API access for repository management, file operations, and search functionality
Read and write records, manage bases and tables in Airtable directly from Claude [TEST UPDATE]
Official MCP server providing secure file system operations for Claude Desktop and Claude Code
Growing community of AI engineers actively building with Claude
Live in 5 minutes • Growing community