How to Install and Configure MCP Servers in Claude Code: Step-by-Step Guide

Installing MCP servers in Claude Code looks intimidating at first - editing JSON config files, getting API credentials, troubleshooting connection errors. This guide walks through the complete process with real examples. By the end, you'll have working MCP servers connected to Claude Code. ## Prerequisites **What you need before starting:** - Claude Code installed (download from anthropic.com) - Claude Pro or Team plan subscription - API credentials for services you want to connect (Slack token, GitHub token, etc.) - Text editor (VS Code, Sublime, or any editor that handles JSON) ## Understanding the MCP Configuration File Claude Code stores MCP server configuration in a JSON file at: **macOS:** `~/Library/Application Support/Claude/mcp_settings.json` **Windows:** `%APPDATA%\Claude\mcp_settings.json` **Linux:** `~/.config/Claude/mcp_settings.json` If this file doesn't exist yet, create it. Claude Code will read it on startup. ## Basic Configuration Structure The config file lists MCP servers Claude should launch: ```json { "mcpServers": { "server-name": { "command": "path/to/server/executable", "args": ["arg1", "arg2"], "env": { "API_KEY": "your-api-key-here" } } } } ``` Each server has: - **Name:** Identifier you choose (e.g., "slack", "github", "database") - **Command:** Path to the MCP server executable - **Args:** Command-line arguments the server needs - **Env:** Environment variables (usually API keys and credentials) ## Example 1: Installing the GitHub MCP Server Let's install the official GitHub MCP server step-by-step. ### Step 1: Install the Server Package ```bash npm install -g @anthropic-ai/mcp-server-github ``` This installs the GitHub MCP server globally on your system. ### Step 2: Get a GitHub Personal Access Token 1. Go to github.com → Settings → Developer settings → Personal access tokens 2. Click "Generate new token (classic)" 3. Select scopes: `repo` (for private repos) or `public_repo` (for public only) 4. Click "Generate token" 5. Copy the token (you won't see it again) ### Step 3: Add to MCP Configuration Edit `mcp_settings.json`: ```json { "mcpServers": { "github": { "command": "mcp-server-github", "env": { "GITHUB_TOKEN": "ghp_your_token_here" } } } } ``` ### Step 4: Restart Claude Code Quit Claude Code completely and reopen it. The app reads MCP configuration on startup. ### Step 5: Test the Connection Open a conversation in Claude Code and ask: "Can you list the recent pull requests in the anthropics/anthropic-sdk-python repository?" If configured correctly, Claude will query GitHub via the MCP server and show results. ## Example 2: Installing the Slack MCP Server ### Step 1: Install the Server ```bash npm install -g @anthropic-ai/mcp-server-slack ``` ### Step 2: Create a Slack App and Get Token 1. Go to api.slack.com/apps 2. Click "Create New App" → "From scratch" 3. Name it "Claude MCP" and select your workspace 4. Go to "OAuth & Permissions" 5. Add these Bot Token Scopes: - `channels:history` - `channels:read` - `groups:history` - `groups:read` - `search:read` 6. Click "Install to Workspace" 7. Copy the "Bot User OAuth Token" (starts with `xoxb-`) ### Step 3: Add to MCP Configuration ```json { "mcpServers": { "github": { "command": "mcp-server-github", "env": { "GITHUB_TOKEN": "ghp_your_token_here" } }, "slack": { "command": "mcp-server-slack", "env": { "SLACK_BOT_TOKEN": "xoxb-your-token-here" } } } } ``` Note: This adds Slack while keeping GitHub. You can run multiple MCP servers simultaneously. ### Step 4: Restart and Test Restart Claude Code and ask: "What were the most recent messages in the #general channel?" Claude will fetch and summarize recent Slack messages. ## Example 3: Installing the PostgreSQL MCP Server ### Step 1: Install the Server ```bash npm install -g @anthropic-ai/mcp-server-postgres ``` ### Step 2: Get Database Connection String Your PostgreSQL connection string looks like: ``` postgresql://username:password@host:5432/database_name ``` Example: ``` postgresql://admin:secretpass@localhost:5432/company_data ``` ### Step 3: Add to MCP Configuration ```json { "mcpServers": { "database": { "command": "mcp-server-postgres", "args": ["postgresql://admin:secretpass@localhost:5432/company_data"] } } } ``` **Security note:** Connection strings contain passwords. Keep `mcp_settings.json` secure. Don't commit it to version control. ### Step 4: Test with a Query "How many users are in the customers table?" Claude will write and execute the SQL query, then show results. ## Troubleshooting Common Issues ### Problem: "MCP server failed to start" **Cause:** Server executable not found or not installed correctly. **Fix:** 1. Verify installation: `which mcp-server-github` (should show path) 2. Reinstall the server: `npm install -g @anthropic-ai/mcp-server-github` 3. Check command path in config matches actual executable location ### Problem: "Authentication failed" or "Invalid token" **Cause:** API credentials are wrong or missing required permissions. **Fix:** 1. Verify token is copied correctly (no extra spaces) 2. Check token hasn't expired 3. Confirm token has necessary permissions (scopes for Slack, permissions for GitHub) 4. Regenerate token if unsure ### Problem: Claude doesn't seem to use the MCP server **Cause:** Claude doesn't know it should query external data. **Fix:** Be explicit in your questions. Instead of "What happened yesterday?" ask "What messages were posted to Slack yesterday?" to make it clear you want Slack data. ### Problem: Config file changes don't take effect **Cause:** Claude Code hasn't reloaded the configuration. **Fix:** Fully quit Claude Code (Cmd+Q on Mac, not just closing the window) and reopen. Config is only read on startup. ### Problem: JSON syntax error **Cause:** Invalid JSON format (missing comma, quote, or bracket). **Fix:** 1. Use a JSON validator (jsonlint.com) 2. Check for: - Missing commas between servers - Unclosed quotes or brackets - Trailing commas (not allowed in JSON) 3. Copy a working example and modify carefully ## Best Practices **Start with one server:** Install and test one MCP server before adding more. Easier to debug issues. **Use environment variables for secrets:** Don't hardcode API keys. Use environment variables or secure credential storage when possible. **Test incrementally:** After adding each server, restart Claude Code and test before configuring the next one. **Keep a backup:** Copy your working `mcp_settings.json` to a safe location. Easy to restore if you break something. **Check logs:** If servers aren't working, check Claude Code logs (Help → Show Logs) for error messages. ## Next Steps Once you have MCP servers working: 1. Experiment with different queries to understand what each server can do 2. Install additional servers for other tools you use 3. Combine multiple servers in one conversation (e.g., Slack + GitHub + database) 4. Share successful configurations with your team ## Quick Takeaway Installing MCP servers requires three steps: install the server package, get API credentials, and add configuration to `mcp_settings.json`. Each server needs a name, command path, and usually API credentials in environment variables. Start with one server (GitHub is easiest), test thoroughly, then add more. If servers don't work, check: correct installation, valid credentials, proper JSON syntax, and that Claude Code was restarted after config changes. Once configured, MCP servers run automatically whenever Claude Code starts. No ongoing maintenance needed.