# ~/.claude.json

> A file Claude Code writes for itself. It holds your account and MCP servers.

**Field:** Artificial Intelligence  
**Category:** Claude Code  
**Also known as:** .claude.json, Claude Code global config

## Think of it like

It is like a notebook the app keeps for itself. You do not need to open it.

## Definition

~/.claude.json is a file in your home folder that Claude Code writes for itself. It holds your account details and the MCP servers you added for yourself. It also holds state, such as which folders you trust, and global config keys that /config sets. It sits next to the ~/.claude folder, not inside it. If it breaks, Claude Code saves a copy in ~/.claude/backups.

## Example

Emma added a server with claude mcp add, then looked for it in settings.json. It was in ~/.claude.json, where her own servers live.

## Example code

```bash
claude mcp add --transport http docs https://mcp.example.com/mcp
```

This writes the server into ~/.claude.json.

## Why it matters

It explains where your MCP servers and trust choices are kept.

## Common mistake

Looking for it inside the ~/.claude folder. It sits beside that folder, in your home folder.

## Three principles

- **Written by Claude Code.** Not by you.
- **Account and MCP.** And trust.
- **Beside ~/.claude.** Not inside.

## Related terms

- [~/.claude Directory](https://learn.benibix.com/term/ai/home-claude-directory)
- [.mcp.json](https://learn.benibix.com/term/ai/mcp-json-file)
- [claude mcp add Command](https://learn.benibix.com/term/ai/claude-mcp-add-command)

## Told apart from

- [.mcp.json vs ~/.claude.json](https://learn.benibix.com/compare/mcp-json-file-vs-claude-json-file): People think every MCP server lives in .mcp.json. Only the team's do. A server you add for yourself, in one project or in all of them, is saved in ~/.claude.json in your home folder. So .mcp.json goes into git and every teammate sees it, while ~/.claude.json never leaves your machine.
- [~/.claude/settings.json vs ~/.claude.json](https://learn.benibix.com/compare/user-settings-file-vs-claude-json-file): People think ~/.claude.json is the user settings file. It is not. The user settings file is settings.json, inside the .claude folder in your home. Claude Code writes the other file itself. It keeps your account, your MCP servers and the folders you trust there. You edit the settings file by hand, and you rarely need to touch the other one.

---

Source: https://learn.benibix.com/term/ai/claude-json-file
Author: Behnia Zarei (a developer in Vienna, Austria, who builds and teaches data, AI and business intelligence at BENIBIX)
Publisher: BENIBIX Learn (https://learn.benibix.com/)
Last updated: 2026-11-16
Licence: CC BY 4.0 (https://creativecommons.org/licenses/by/4.0/). Quote freely with attribution.
