Skip to content
BranchesTags

Latest commit

 

History

1 Commit

Folders and files

NameName
Last commit message
Last commit date
README.md
README.md
 
 

Repository files navigation

Claude MCP Guide

Reference guide for adding and managing MCP (Model Context Protocol) servers in Claude Code CLI and Claude Desktop.

Table of Contents

What is MCP?

The Model Context Protocol is an open standard that lets AI assistants connect to external tools and data sources. MCP servers expose "tools" that Claude can call — things like reading databases, calling APIs, managing files, etc.

MCP servers communicate over one of three transports:

  • stdio — Claude spawns the server as a subprocess and communicates over stdin/stdout (most common for local servers)
  • SSE — Server-Sent Events over HTTP
  • HTTP — Streamable HTTP transport

Claude Code CLI

Adding a Server

claude mcp add <server-name> [options] -- <command> [args...]

The -- separates Claude's options from the server command. Everything after -- is the command used to start the MCP server.

Transport Types

# stdio (default) — runs a local process
claude mcp add my-server -- node /path/to/server.js

# HTTP/SSE — connects to a remote URL
claude mcp add my-server --transport http https://example.com/mcp

# SSE (legacy)
claude mcp add my-server --transport sse https://example.com/sse

Scope Options

Flag Scope Config File Description
-s user User (global) ~/.claude.json Available in all projects
-s project Project .mcp.json (project root) Available only in this project, can be shared via git 
# Global — available everywhere
claude mcp add my-server -s user -- node server.js

# Project-only — lives in .mcp.json, can be committed
claude mcp add my-server -s project -- node server.js

Environment Variables

Pass environment variables with -e:

claude mcp add my-server \
  -e API_KEY=sk-abc123 \
  -e DATABASE_URL=postgres://localhost/db \
  -- node server.js

Managing Servers

# List all configured servers and their health
claude mcp list

# Remove a server
claude mcp remove <server-name> -s user    # remove from user scope
claude mcp remove <server-name> -s project # remove from project scope

# Reconnect servers (in an active session)
/mcp

Claude Desktop

Config File Location

OS Path
macOS ~/Library/Application Support/Claude/claude_desktop_config.json
Windows %APPDATA%\Claude\claude_desktop_config.json

Configuration Format

{
  "mcpServers": {
    "server-name": {
      "command": "node",
      "args": ["/path/to/server.js", "--flag"],
      "env": {
        "API_KEY": "your-key",
        "OTHER_VAR": "value"
      }
    }
  }
}

After editing, restart Claude Desktop to pick up changes.

Common Patterns

npm Package (npx)

For published MCP servers on npm:

# Claude Code CLI
claude mcp add my-server -- npx -y some-mcp-package

# Claude Desktop
{
  "command": "npx",
  "args": ["-y", "some-mcp-package"]
}

The -y flag auto-confirms the npx install prompt.

Local Node.js Server

For a server you've cloned and built locally:

# Claude Code CLI
claude mcp add my-server -- node /path/to/build/index.js

# Claude Desktop
{
  "command": "node",
  "args": ["/path/to/build/index.js"]
}

Python Server

# Claude Code CLI
claude mcp add my-server -- python /path/to/server.py

# Using uvx (Python package runner, like npx for Python)
claude mcp add my-server -- uvx some-mcp-package

# Claude Desktop
{
  "command": "python",
  "args": ["/path/to/server.py"]
}

Docker Container

# Claude Code CLI
claude mcp add my-server -- docker run -i --rm \
  -e API_KEY=value \
  some-image:latest

# Claude Desktop
{
  "command": "docker",
  "args": [
    "run", "-i", "--rm",
    "-e", "API_KEY=value",
    "some-image:latest"
  ]
}

-i (interactive) is required for stdio transport so Docker keeps stdin open. --rm cleans up the container after it exits.

Remote HTTP/SSE Server

# Claude Code CLI
claude mcp add my-server --transport http https://example.com/mcp

# With auth header
claude mcp add my-server --transport http https://example.com/mcp \
  --header "Authorization:Bearer your-token"

For Claude Desktop, use mcp-remote to bridge remote servers:

{
  "command": "npx",
  "args": [
    "mcp-remote",
    "https://example.com/sse",
    "--header",
    "Authorization:${AUTH_HEADER}"
  ],
  "env": {
    "AUTH_HEADER": "Bearer your-token"
  }
}

Real-World Examples

Actual Budget MCP

Personal finance tool integration:

# Claude Code CLI
claude mcp add actual-budget \
  -s user \
  -e ACTUAL_SERVER_URL=https://your-actual-server.com \
  -e ACTUAL_PASSWORD=your-password \
  -e ACTUAL_BUDGET_SYNC_ID=your-budget-id \
  -e DOTENV_CONFIG_QUIET=true \
  -- node /path/to/actual-mcp/build/index.js --enable-write
// Claude Desktop
{
  "mcpServers": {
    "actual-budget": {
      "command": "node",
      "args": ["/path/to/actual-mcp/build/index.js", "--enable-write"],
      "env": {
        "ACTUAL_SERVER_URL": "https://your-actual-server.com",
        "ACTUAL_PASSWORD": "your-password",
        "ACTUAL_BUDGET_SYNC_ID": "your-budget-id",
        "DOTENV_CONFIG_QUIET": "true"
      }
    }
  }
}

DOTENV_CONFIG_QUIET=true is needed because dotenv v17+ prints to stdout, which corrupts the stdio MCP transport.

--enable-write enables write tools (create/update/delete transactions, categories, etc.).

Linear MCP

Project management integration (remote HTTP):

# Claude Code CLI
claude mcp add linear --transport http https://mcp.linear.app/mcp

Linear handles auth via OAuth in the browser when you first connect.

Playwright MCP

Browser automation:

# Claude Code CLI
claude mcp add playwright -- npx @anthropic-ai/mcp-server-playwright@latest
// Claude Desktop
{
  "mcpServers": {
    "playwright": {
      "command": "npx",
      "args": ["@anthropic-ai/mcp-server-playwright@latest"]
    }
  }
}

Notion MCP

Notion workspace integration (remote HTTP):

# Claude Code CLI
claude mcp add notion --transport http https://mcp.notion.com/mcp

Filesystem MCP

Give Claude access to specific directories:

# Claude Code CLI
claude mcp add filesystem -- npx -y @modelcontextprotocol/server-filesystem /path/to/allowed/dir
// Claude Desktop
{
  "mcpServers": {
    "filesystem": {
      "command": "npx",
      "args": [
        "-y",
        "@modelcontextprotocol/server-filesystem",
        "/Users/you/Documents",
        "/Users/you/Projects"
      ]
    }
  }
}

Troubleshooting

"Unexpected token" / "not valid JSON"

The server is printing non-JSON output to stdout, corrupting the stdio transport. Common causes:

  • dotenv v17+ prints a log line to stdout. Fix: set DOTENV_CONFIG_QUIET=true in env vars.
  • console.log() in server code. MCP servers must only write protocol messages to stdout. Use console.error() for logging.

"Server disconnected"

  • Check the server can run standalone: node /path/to/server.js --test-resources (if supported)
  • Verify env vars are correct
  • Check for version mismatches (e.g., API library older than the server it connects to)

"out-of-sync-migrations"

For Actual Budget specifically: your @actual-app/api npm package version is older than your Actual Budget server. Upgrade the package:

npm install @actual-app/api@latest
npm run build

Server shows "Connected" but no tools appear

  • Restart the Claude Code session or Claude Desktop
  • Some servers need flags to enable tools (e.g., --enable-write for actual-mcp)
  • Check claude mcp list to verify connection status

Permission errors

  • Ensure the server binary/script is executable
  • For Docker, ensure Docker Desktop is running
  • For npx, ensure npm/node is on your PATH

Tips

  • Use claude mcp list regularly to check server health.
  • Use -s project and commit .mcp.json to share MCP config with your team (but keep secrets in env vars or a separate .env).
  • Use DOTENV_CONFIG_QUIET=true any time a server uses dotenv v17+.
  • Test servers locally first before adding them to Claude. Run the server command directly and check for errors on stderr.
  • Keep MCP server packages updated to avoid version mismatches with the services they connect to.
  • Use /mcp in Claude Code to reconnect servers without restarting the session.

Last updated: February 2026

About

Reference guide for adding and managing MCP servers in Claude Code CLI and Claude Desktop

Resources

Readme
Activity

Stars

3 stars

Watchers

0 watching

Forks

1 fork
Report repository

Releases

Packages

Contributors