┌─────────────────┐     stdio      ┌─────────────────┐
│ Claude Desktop  │ ←────────────→ │   MCP Server 1  │
│   (MCP Client)  │                │  (Your Tools)   │
│                 │     stdio      ├─────────────────┤
│                 │ ←────────────→ │   MCP Server 2  │
│                 │                │ (More Tools)    │
└─────────────────┘                └─────────────────┘

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

%APPDATA%\Claude\claude_desktop_config.json

~/.config/Claude/claude_desktop_config.json

# macOS
mkdir -p ~/Library/Application\ Support/Claude
echo '{"mcpServers":{}}' > ~/Library/Application\ Support/Claude/claude_desktop_config.json

# Linux
mkdir -p ~/.config/Claude
echo '{"mcpServers":{}}' > ~/.config/Claude/claude_desktop_config.json

New-Item -ItemType Directory -Force -Path "$env:APPDATA\Claude"
'{"mcpServers":{}}' | Set-Content "$env:APPDATA\Claude\claude_desktop_config.json"

{
  "mcpServers": {
    "server-name": {
      "command": "executable",
      "args": ["arg1", "arg2"],
      "env": {
        "KEY": "value"
      }
    }
  }
}

{
  "mcpServers": {
    "my-server": {
      "command": "npx",
      "args": ["tsx", "/Users/you/my-server/src/index.ts"],
      "env": {
        "NODE_ENV": "production",
        "LOG_LEVEL": "info"
      }
    }
  }
}

{
  "mcpServers": {
    "my-server": {
      "command": "node",
      "args": ["/Users/you/my-server/dist/index.js"]
    }
  }
}

{
  "mcpServers": {
    "data-analysis": {
      "command": "/Users/you/my-server/venv/bin/python",
      "args": ["/Users/you/my-server/server.py"],
      "env": {
        "PYTHONUNBUFFERED": "1",
        "DATA_DIR": "/Users/you/datasets"
      }
    }
  }
}

{
  "mcpServers": {
    "filesystem": {
      "command": "npx",
      "args": [
        "-y",
        "@modelcontextprotocol/server-filesystem",
        "/Users/you/Documents"
      ]
    },
    "github": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-github"],
      "env": {
        "GITHUB_TOKEN": "${GITHUB_TOKEN}"
      }
    }
  }
}

{
  "mcpServers": {
    "filesystem": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-filesystem", "/Users/you/projects"]
    },
    "database": {
      "command": "node",
      "args": ["/Users/you/mcp-servers/postgres/dist/index.js"],
      "env": {
        "DATABASE_URL": "${DATABASE_URL}"
      }
    },
    "notes": {
      "command": "npx",
      "args": ["tsx", "/Users/you/mcp-servers/notes/src/index.ts"]
    }
  }
}

# Add a server using npx
claude mcp add filesystem npx @modelcontextprotocol/server-filesystem /Users/you/Documents

# Add a custom server
claude mcp add my-notes npx tsx /Users/you/my-server/src/index.ts

# Add with environment variables
claude mcp add github npx @modelcontextprotocol/server-github -e GITHUB_TOKEN=ghp_xxx

# List configured servers
claude mcp list

# Remove a server
claude mcp remove my-notes

import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
import { z } from 'zod';

const server = new McpServer({
  name: 'my-claude-server',
  version: '1.0.0',
});

// Register tools with rich descriptions for Claude
server.tool(
  'analyzeCode',
  'Analyze source code for potential improvements, bugs, and security issues',
  {
    code: z.string().describe('The source code to analyze'),
    language: z.enum(['javascript', 'typescript', 'python', 'java']).describe('Programming language'),
    focus: z.array(z.enum(['performance', 'security', 'readability', 'bugs'])).optional(),
  },
  async ({ code, language, focus }) => {
    const analysis = await performAnalysis(code, language, focus);
    return {
      content: [{ type: 'text', text: formatAnalysis(analysis) }],
    };
  }
);

// All logging goes to stderr
console.error('Starting server...');

const transport = new StdioServerTransport();
await server.connect(transport);
console.error('Server connected to Claude');

import sys
from mcp.server.fastmcp import FastMCP

mcp = FastMCP("my-claude-server")

@mcp.tool()
def analyze_code(code: str, language: str) -> str:
    """Analyze source code for improvements and bugs.

    Args:
        code: The source code to analyze
        language: Programming language (javascript, python, etc.)
    """
    # All logging to stderr
    print("Analyzing code...", file=sys.stderr)
    analysis = perform_analysis(code, language)
    return format_analysis(analysis)

if __name__ == "__main__":
    mcp.run()

// Good: clear, specific, actionable
server.tool('searchFiles', {
  description: 'Search for files by name or content pattern within the project directory. Use this when the user asks to find or locate specific files.',
  inputSchema: {
    pattern: z.string().describe('Glob pattern or text to search for'),
    directory: z.string().optional().describe('Subdirectory to search in, defaults to project root'),
  },
}, handler);

// Bad: vague, no context
server.tool('search', {
  description: 'Searches for things',
  inputSchema: { q: z.string() },
}, handler);

# Send an initialize request
echo '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-03-26","capabilities":{},"clientInfo":{"name":"test","version":"1.0.0"}}}' | npx tsx src/index.ts

# Check JSON syntax
python3 -m json.tool < ~/Library/Application\ Support/Claude/claude_desktop_config.json

{
  "mcpServers": {
    "filesystem": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-filesystem", "/Users/dev/projects"]
    },
    "git": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-github"],
      "env": { "GITHUB_TOKEN": "${GITHUB_TOKEN}" }
    },
    "database": {
      "command": "npx",
      "args": ["tsx", "/Users/dev/mcp-servers/postgres/src/index.ts"],
      "env": { "DATABASE_URL": "postgresql://localhost/devdb" }
    }
  }
}

{
  "mcpServers": {
    "papers": {
      "command": "python3",
      "args": ["/Users/researcher/mcp-servers/arxiv/server.py"],
      "env": { "CACHE_DIR": "/Users/researcher/.cache/arxiv" }
    },
    "notes": {
      "command": "npx",
      "args": ["tsx", "/Users/researcher/mcp-servers/obsidian/src/index.ts"],
      "env": { "VAULT_PATH": "/Users/researcher/Documents/Obsidian" }
    }
  }
}