Claude Code Initial Setup Complete Guide: Installation, CLAUDE.md, MCP Servers & Custom Slash Commands
Claude Code Initial Setup Complete Guide
Claude Code is Anthropic’s agentic coding tool that lives in your terminal, understands your codebase, and helps you code faster through natural language. This guide walks you through every step—from installation to advanced configuration—so you can unlock its full potential from day one.
Step 1: Install Claude Code
Claude Code requires Node.js 18+ and runs on macOS, Linux, and Windows (via WSL or native). Install it globally using npm:
# Install Claude Code globally
npm install -g @anthropic-ai/claude-code
Verify installation
claude —version
Launch Claude Code in your project directory
cd /path/to/your/project
claude
On first launch, Claude Code will guide you through authentication. You can authenticate via your Anthropic Console account or by setting an API key:
# Option A: Interactive login (opens browser)
claude login
Option B: Set API key directly
export ANTHROPIC_API_KEY=YOUR_API_KEY
Option C: Use a configuration file
claude config set apiKey YOUR_API_KEY
Step 2: Create and Configure CLAUDE.md
The CLAUDE.md file is the single most important configuration file for Claude Code. It acts as persistent instructions that Claude reads at the start of every conversation. You can place it at multiple levels:
- **Project root** — ./CLAUDE.md (checked into version control, shared with team)- **User-level** — ~/.claude/CLAUDE.md (private, applies to all projects)- **Nested directories** — ./src/CLAUDE.md (loaded when working in that subtree)Here is a practical CLAUDE.md template:
# Project Instructions for Claude Code
Project Overview
- Stack: Next.js 14 + TypeScript + Tailwind CSS + Prisma
- Node version: 20.x
- Package manager: pnpm
Code Conventions
- Use functional components with TypeScript interfaces
- Prefer named exports over default exports
- Use server components by default; add “use client” only when needed
- Test files live alongside source: Component.test.tsx
Commands
- Build: pnpm build
- Test: pnpm test
- Lint: pnpm lint —fix
- Dev: pnpm dev
Important Rules
- NEVER modify migration files directly
- Always run “pnpm test” after making changes
Use environment variables from .env.local, never hardcode secrets
Tips for Effective CLAUDE.md Files
- Keep instructions actionable and specific—avoid vague guidance- Include the commands Claude should run for building, testing, and linting- Document project-specific conventions that differ from common defaults- Update it as your project evolves; treat it like living documentation
Step 3: Connect MCP Servers
Model Context Protocol (MCP) servers extend Claude Code with external tool integrations—databases, APIs, design tools, and more. Configure them in .mcp.json at your project root or in ~/.claude/settings.json globally.
// .mcp.json (project-level MCP configuration)
{
"mcpServers": {
"context7": {
"command": "npx",
"args": ["-y", "@upstash/context7-mcp"]
},
"filesystem": {
"command": "npx",
"args": ["-y", "@modelcontextprotocol/server-filesystem", "/path/to/allowed/dir"]
},
"postgres": {
"command": "npx",
"args": ["-y", "@modelcontextprotocol/server-postgres"],
"env": {
"DATABASE_URL": "postgresql://user:password@localhost:5432/mydb"
}
}
}
}
You can also add MCP servers interactively:
# Add an MCP server via CLI
claude mcp add context7 -- npx -y @upstash/context7-mcp
List configured MCP servers
claude mcp list
Remove an MCP server
claude mcp remove context7
Step 4: Set Up Custom Slash Commands
Custom slash commands let you create reusable prompt templates. Store them as Markdown files in .claude/commands/ at the project level or ~/.claude/commands/ for global access.
# Create the commands directory
mkdir -p .claude/commands
Create a code review command
cat > .claude/commands/review.md << ‘EOF’
Review the current git diff for:
- Security vulnerabilities (injection, XSS, secrets)
- Performance issues (N+1 queries, memory leaks)
- Logic errors and edge cases
- Adherence to project conventions in CLAUDE.md
Provide a summary with severity ratings: critical, warning, info.
EOF
Create a test generation command
cat > .claude/commands/gen-tests.md << ‘EOF’
Generate comprehensive tests for $ARGUMENTS:
- Unit tests for pure functions
- Integration tests for API endpoints
- Edge cases and error scenarios
Use the testing conventions from CLAUDE.md EOFUse them in Claude Code by typing
/reviewor/gen-tests src/utils/auth.ts. The$ARGUMENTSplaceholder captures any text you type after the command name.
Step 5: Configure Permissions and Settings
Fine-tune Claude Code’s behavior through settings:
# Set permission mode (default: normal)
claude config set permissions.mode auto-accept # Trust all tools
claude config set permissions.mode normal # Ask before risky actions
Configure preferred model
claude config set model claude-opus-4-6
Set default context
claude config set maxContext 200000
View all current settings
claude config list
Pro Tips for Power Users
| Tip | Details |
|---|---|
Use /compact regularly | Compresses conversation context when working on long tasks, preserving key information while freeing token space |
| Pipe input to Claude | git diff | claude "Review this diff for bugs" sends the diff as context for a one-shot response |
Multi-turn with --continue | claude --continue resumes the most recent conversation from where you left off |
| Headless mode for CI | claude --print "Generate changelog from recent commits" outputs the response and exits—perfect for pipelines |
| Memory system | Tell Claude to "remember" preferences; it stores them in ~/.claude/projects//memory/ for future sessions |
| Parallel tool calls | Claude Code can read multiple files and run independent operations simultaneously for faster execution |
| Error | Cause | Solution |
|---|---|---|
ANTHROPIC_API_KEY not set | Missing or invalid API key | Run claude login or export ANTHROPIC_API_KEY=YOUR_API_KEY |
MCP server failed to start | Server binary not found or missing deps | Run the MCP server command manually to check for errors; ensure npx has network access |
CLAUDE.md not loaded | File is outside the project root or misspelled | Verify filename is exactly CLAUDE.md (case-sensitive) and is in the working directory |
Permission denied on tool execution | Permission mode is restrictive | Approve the action when prompted, or set permissions.mode to auto-accept for trusted projects |
| Slow startup | Too many MCP servers or large CLAUDE.md | Remove unused MCP servers; keep CLAUDE.md concise and under 2000 words |
Can I use Claude Code with an existing project that already has other AI tool configurations?
Yes. Claude Code's configuration files (CLAUDE.md, .mcp.json, .claude/commands/) are independent and will not conflict with configurations for tools like GitHub Copilot, Cursor, or Cody. You can run Claude Code alongside any other AI-assisted development tool. Simply add its config files to your project and optionally add .claude/ to your .gitignore if you prefer to keep personal settings private.
How do I share CLAUDE.md and custom commands with my team?
Commit the project-level CLAUDE.md and .claude/commands/ directory to your repository. These files serve as shared team conventions that Claude Code will follow for every team member. For personal preferences—like your own slash commands or user-specific instructions—use the global /.claude/CLAUDE.md/.claude/commands/ directory, which are not checked into version control.
Do MCP servers consume API tokens or add to the cost?
MCP server tool definitions and their results are included in the context sent to the model, so they do contribute to token usage. However, tools are only invoked when relevant to your task. To minimize cost, remove MCP servers you are not actively using from your .mcp.json configuration, and prefer project-level configuration over global so servers only load when needed.