🗂️

claude.json

The global configuration file for Claude Code sessions. Stores MCP server definitions, project specific overrides, and session metadata. The central registry for all external integrations.

Configuration·2 sections·1 min read

codingdevops

Install Prompt

Paste this into Claude Code to set it up:

The file lives at ~/.claude.json. It stores global MCP server configurations and project specific overrides. IMPORTANT: Claude Code continuously writes to this file, so never edit it with a text editor while a session is running. Use jq via the command line for atomic modifications instead.

01What It Does

Two roles in one file

The ~/.claude.json file serves a dual purpose. At the top level, the "mcpServers" key defines MCP servers available in every Claude Code session, regardless of which project you are working in. These are your global integrations: GitHub, Firecrawl, Notion, Slack, and anything else you use across projects.

Under the "projects" key, you can define project specific MCP server configurations that only activate when you are working inside that directory. This lets you keep project scoped integrations (like a local Supabase instance or a project specific API) separate from your global setup. Claude Code also writes session metrics, caches, and internal state to this file during every session.

02Editing Safely

Never edit with a text editor during a session

Claude Code writes to ~/.claude.json continuously during sessions (session metrics, caches, feature flags). If you open it in a text editor, make changes, and save, you will likely overwrite data Claude Code just wrote, or your changes will be overwritten moments later.

Use jq via the command line instead. It reads, modifies, and writes atomically in a single pipeline:

jq '.mcpServers["server-name"] = {"type": "http", "url": "https://example.com/mcp"}' ~/.claude.json > /tmp/claude-json-tmp && mv /tmp/claude-json-tmp ~/.claude.json

This pattern works for adding, updating, and removing MCP servers. For viewing the current configuration, use jq '.mcpServers' ~/.claude.json. Always restart Claude Code after making changes so the new configuration is loaded.