Claude Code with DeepSeek V4: Full Setup Guide

Abstract

This article provides a deep dive into the global ~/.claude/settings.json configuration file, covering environment variable routing, model alias mapping, permission controls, and macOS‑native notification hooks, while also dissecting the accompanying ~/.mcp.json that integrates five major MCP servers for browser automation, game development, documentation retrieval, and Git operations. Together, they form a unified cross‑platform stack that runs seamlessly on macOS, Windows, and Linux, masterfully balancing development efficiency, local system security, and toolchain extensibility.

1. Core Background: Connecting Claude Code with DeepSeek V4 API Endpoints

Claude Code exposes a set of standardized environment variables that separate the local coding client from the backend model provider. This design allows developers to replace the default Anthropic endpoint with a third-party compatible API service. In most cases, the key change is the ANTHROPIC_BASE_URL field.

DeepSeek introduced an Anthropic-compatible API gateway in early 2026 at:

https://api.deepseek.com/anthropic

This endpoint follows Claude’s request structure, authentication pattern, message format, and token billing logic. It also supports DeepSeek’s V4 model family, including DeepSeek-V4-Pro[1m] and DeepSeek-V4-Flash.

The Pro model provides a 1,000,000-token context window. It is designed for full-repository code analysis, multi-file refactoring, long-document reasoning, and complex agentic workflows. Its long-context capability is supported by a hybrid attention design based on CSA, or Compressed Sparse Attention, and HCA, or Heavily Compressed Attention. This architecture reduces KV cache memory pressure and improves the feasibility of large-context inference.

The Flash model is built for faster, lighter tasks. It is more suitable for short dialogue, text extraction, quick code suggestions, and low-latency development scenarios. It trades part of the deep reasoning capacity of the Pro model for better response speed and lower usage cost.

The configuration discussed in this article standardizes model routing across Claude’s native model tiers. It maps Haiku-style workloads to Flash and routes Sonnet, Opus, reasoning, and subagent workloads to Pro. This allows developers to keep using familiar Claude Code workflows while changing the backend inference provider.

The complete setup consists of four main parts:

• Environment routing and model assignment through env
• Local command permission control through permissions
• Runtime notification handling through hooks
• External tool expansion through ~/.mcp.json

Together, these files create a portable configuration stack for new developer workstations.

2. Full Breakdown of ~/.claude/settings.json

The global Claude Code configuration file is stored under the hidden .claude directory:

~/.claude/settings.json

This file applies at the user level. Once configured, it affects all Claude Code sessions running under the same local account. The setup contains three core modules: env, permissions, and hooks.

2.1 Env Section: Backend Routing, Model Mapping, and Inference Tuning

The env object controls API forwarding, model alias binding, context behavior, and inference timeout settings. In the shared template, it includes ten key parameters.

1. ANTHROPIC_AUTH_TOKEN

This field stores the DeepSeek API key. It replaces the native Anthropic access token when Claude Code traffic is routed to DeepSeek’s compatible endpoint.

"ANTHROPIC_AUTH_TOKEN": "your_deepseek_api_key"

All requests sent by Claude Code will use this token for backend authentication.

2. ANTHROPIC_BASE_URL

This is the most important routing parameter. It redirects Claude Code requests to DeepSeek’s Anthropic-compatible API endpoint.

"ANTHROPIC_BASE_URL": "https://api.deepseek.com/anthropic"

After this field is configured, Claude Code no longer sends requests to the default Anthropic endpoint. Instead, it forwards traffic to DeepSeek’s compatible inference gateway.

3. Claude Tier Alias Mapping

The configuration maps Claude’s native tier names to DeepSeek V4 models:

"ANTHROPIC_DEFAULT_HAIKU_MODEL": "deepseek-v4-flash",
"ANTHROPIC_DEFAULT_OPUS_MODEL": "deepseek-v4-pro[1m]",
"ANTHROPIC_DEFAULT_SONNET_MODEL": "deepseek-v4-pro[1m]"

This mapping creates a simple task split.

Haiku-style tasks are routed to deepseek-v4-flash. These usually include lightweight interactions, quick prompts, and low-latency jobs.

Sonnet and Opus-style tasks are routed to deepseek-v4-pro[1m]. These are better suited for complex reasoning, long-context workflows, and full-codebase operations.

4. Universal Model Fallback Rules

The template also defines fallback model settings:

"ANTHROPIC_MODEL": "deepseek-v4-pro[1m]",
"ANTHROPIC_REASONING_MODEL": "deepseek-v4-pro[1m]",
"CLAUDE_CODE_SUBAGENT_MODEL": "deepseek-v4-pro[1m]"

These settings ensure that the main agent, reasoning tasks, and subagent executions all use the Pro model by default. This is useful for workflows that require consistent context handling across multiple internal steps.

5. API_TIMEOUT_MS

The timeout threshold is set to 1,200,000 milliseconds:

"API_TIMEOUT_MS": "1200000"

This equals 20 minutes. The extended timeout is important for large repository analysis, long-running refactoring, and multi-step agent tasks. Without this setting, heavy inference tasks may terminate before completion.

6. CLAUDE_AUTOCOMPACT_PCT_OVERRIDE

The automatic context compression threshold is set to 80%:

"CLAUDE_AUTOCOMPACT_PCT_OVERRIDE": "80"

When the active session reaches 80% of the maximum context capacity, Claude Code begins compacting the conversation context. This helps preserve important information while controlling memory pressure and inference latency.

7. CLAUDE_CODE_EFFORT_LEVEL

The reasoning effort level is configured as:

"CLAUDE_CODE_EFFORT_LEVEL": "max"

This setting enables the highest reasoning intensity. It is useful for complex debugging, architectural planning, mathematical reasoning, and multi-step tool orchestration.

Overall, the env section removes the need for repeated manual model selection. Developers can continue using Claude Code’s standard model labels, while the backend automatically routes each task to the configured DeepSeek V4 model.

2.2 Permissions Section: Whitelist-First Security Governance for Shell Operations

The permissions module controls how Claude Code handles local file edits and terminal commands. The configuration adopts a whitelist-first strategy with targeted blocking for dangerous operations.

This design reduces unnecessary prompts during normal development. At the same time, it creates firm boundaries around commands that may damage the local system.

1. Global Allow Rule

"allow": ["*"]

This wildcard rule allows standard development operations by default. It covers common file edits, terminal reads, and lightweight script execution.

The goal is to avoid excessive confirmation popups during normal coding sessions.

2. Default Edit Mode

"defaultMode": "acceptEdits"

This setting allows Claude Code to apply file edits automatically. It is especially useful for refactoring, documentation updates, and repetitive code changes.

Riskier shell commands still require additional review when they match the ask list.

3. Conditional Prompt Rules

The ask array defines commands that require human approval before execution.

"Bash(sudo :*)"
"Bash(curl :* | bash :*)"
"Bash(:* | sh :*)"

These rules cover three high-risk categories:

• Commands executed with root privileges
• Remote scripts piped directly into local execution
• Generic shell pipelines that pass content into sh

These patterns are common in setup scripts, dependency installers, and automation snippets. They are not always malicious, but they deserve manual review.

4. Permanent Deny Rules

The deny array blocks destructive commands entirely.

"Bash(rm -rf :*)"
"Bash(:* > /dev/sda :*)"
"Bash(:* :* > /etc/:*)"
"Bash(chmod 777 :*)"

These rules prevent four types of high-impact operations:

• Recursive directory deletion
• Raw disk overwriting
• System configuration file overwriting
• Unrestricted full file permission changes

This layered permission model solves a common problem in AI coding tools. Developers do not want constant prompts for safe edits. However, they still need strong protection against irreversible system-level actions.

With this configuration, routine work becomes smoother, while dangerous commands remain controlled.

2.3 Hooks Section: macOS Native Event Notification Triggers

The hooks module connects Claude Code runtime events to local notification scripts. In the original configuration, these hooks are implemented with macOS AppleScript commands through osascript.

Each event uses a different notification message and system alert sound.

1. Stop

This hook runs when a task completes successfully. It displays a macOS notification titled Claude Code with the message:

任务已完成

It uses the Glass system alert sound.

2. StopFailure

This hook runs when a task fails or terminates abnormally. It displays a failure notification and uses the Basso sound. This makes errors easier to notice during long-running sessions.

3. PermissionRequest

This hook runs when Claude Code needs human approval for a command in the ask list. It uses the Ping sound, which is suitable for low-priority prompts.

4. PostToolUseFailure

This hook runs when an external tool or MCP server call fails. It uses the Frog sound to distinguish tool errors from normal task failures.

These hooks are macOS-specific. On Windows and Linux, the notification commands need to be replaced.

For Windows, PowerShell toast notifications are a more suitable option. For Linux desktops, libnotify or notify-send can be used. The hook rules can be reloaded through the /hooks command after configuration changes.

3. MCP Server Orchestration Through ~/.mcp.json

The Model Context Protocol, or MCP, is a client-server standard for connecting Claude Code with external tools. It allows the AI coding client to interact with browsers, documentation systems, game engines, and Git platforms through structured tool calls.

The supplementary configuration file is stored at:

~/.mcp.json

The shared setup integrates five MCP servers.

3.1 Playwright MCP

Playwright MCP is launched through the global npm command:

playwright-mcp

It enables automated browser workflows. Common use cases include page rendering, form filling, screenshot capture, UI inspection, and frontend regression testing.

This connector is especially useful for full-stack web development. It allows Claude Code to verify frontend behavior instead of only editing source files.

3.2 Godot MCP

Godot MCP is launched with:

godot-mcp

It provides integration with the Godot game engine editor. Developers can use it for node manipulation, scene updates, animation timeline adjustments, and asset iteration.

This is useful for independent game developers who want AI assistance inside a visual engine workflow.

3.3 Context7 MCP

Context7 MCP is executed through:

context7-mcp

Its main purpose is documentation retrieval. It provides up-to-date references for third-party libraries, frameworks, and version-specific APIs.

This helps reduce hallucinated code suggestions. It also improves accuracy when working with fast-changing libraries.

3.4 Godot Docs MCP

The Godot Docs MCP server is launched with:

mcp-server-godot-docs

It requires a local GODOT_PATH environment variable. On macOS, the path may look like this:

/Applications/Godot.app/Contents/MacOS/Godot

This server focuses on offline Godot documentation lookup. It complements the Godot editor connector by giving the AI client direct access to engine-specific references.

3.5 GitHub MCP Server

The GitHub MCP server is started with:

github-mcp-server stdio

It supports repository operations such as pull request creation, issue tracking, commit review, branch inspection, and release workflow management.

The shared template uses stdio transport for all five connectors. This keeps local communication lightweight and avoids unnecessary network complexity for single-workstation development.

Before the configuration takes effect, all MCP server packages must be installed globally:

npm install -g [server-name]

Together, these five servers create a complete development toolchain. The stack covers browser automation, game development, documentation lookup, and Git repository management.

4. Standardized Cross-Platform Deployment Workflow

The original setup can be deployed across macOS, Windows, and Linux. The core workflow is the same, but notification hooks require platform-specific changes.

Step 1: Create the Claude Code Configuration File

Create the user-level configuration directory and write the JSON template to:

~/.claude/settings.json

Then replace the placeholder value in ANTHROPIC_AUTH_TOKEN with a valid DeepSeek API key. Also confirm that the base URL is set to:

https://api.deepseek.com/anthropic

Step 2: Install MCP Servers and Write ~/.mcp.json

Install the required MCP packages through npm. Then place the MCP configuration file at:

~/.mcp.json

If the Godot-related servers are enabled, update GODOT_PATH to match the local Godot binary path.

Step 3: Adapt Notification Hooks

The original hooks use macOS osascript, so they only work on macOS.

For Windows, replace them with PowerShell notification commands. For Linux, use notify-send or another libnotify-compatible tool.

This step is optional, but it improves visibility during long-running AI coding tasks.

Step 4: Reload Claude Code Runtime Configuration

After the files are updated, restart Claude Code or reload hooks through:

/hooks

This activates the updated environment variables, permission rules, and MCP server connections.

Post-Deployment Validation

After setup, developers should run two basic checks.

First, run a long-context code analysis task. This verifies that the 20-minute API timeout works as expected.

Second, trigger a restricted command pattern such as a sudo command. This confirms that the permission prompt logic is active.

5. Design Tradeoffs and Practical Value

5.1 Core Efficiency Advantages

This configuration provides several practical benefits.

First, unified DeepSeek V4 routing reduces credential management overhead. Developers no longer need to maintain separate endpoint settings for each local Claude Code session.

Second, the 1-million-token Pro model improves long-context workflows. It allows Claude Code to analyze larger repositories and longer documents without constant manual file splitting.

Third, the 80% automatic context compression rule helps preserve session continuity. It reduces the risk of losing important context during long-running tasks.

Fourth, the whitelist-first permission model improves daily coding efficiency. It avoids unnecessary prompts for normal edits while still blocking destructive commands.

Fifth, the MCP integration removes repeated tool setup work. Browser testing, GitHub operations, documentation retrieval, and Godot workflows can all be connected through a single configuration file.

5.2 Inherent Tradeoffs and Mitigation Strategies

The template also includes several tradeoffs.

The first tradeoff is the 20-minute timeout. It is useful for heavy workloads, but it may keep connections open longer than necessary. For lightweight projects, developers can reduce API_TIMEOUT_MS to:

"API_TIMEOUT_MS": "300000"

This sets the timeout to 5 minutes.

The second tradeoff is the max reasoning effort level. It improves reasoning quality, but it may increase token consumption for simple tasks.

One mitigation strategy is to define project-level overrides in:

.claude/settings.json

For low-complexity projects, developers can route more tasks to deepseek-v4-flash. This helps control cost while keeping Pro available for complex workflows.

6. Industrial Application Scenarios

This configuration stack is most useful for three groups of developers.

6.1 Full-Stack Web Engineers

Full-stack developers can benefit from the combination of DeepSeek V4 Pro, Playwright MCP, and GitHub MCP.

The Pro model provides long-context reasoning for backend and frontend codebases. Playwright MCP adds browser-level validation. GitHub MCP supports repository-level operations such as pull request review and branch management.

This creates a more complete AI-assisted development loop.

6.2 Independent Game Developers

Game developers using Godot can benefit from the two Godot-related MCP servers.

Godot MCP supports direct editor interaction. Godot Docs MCP provides offline documentation lookup. Together, they make it easier to iterate on scenes, scripts, assets, and engine-specific APIs.

This is useful for small teams or solo developers who need faster prototyping.

6.3 Enterprise R&D Teams

Enterprise engineering teams often maintain large codebases with complex dependencies. In these environments, DeepSeek-V4-Pro[1m] is valuable because it can process more repository context in a single session.

The permission system is also important for enterprise environments. It reduces unnecessary interruptions while blocking dangerous local operations.

For shared engineering teams, the full configuration can be packaged as a dotfiles repository. This makes it easier to provision new workstations with consistent model routing, permission rules, and MCP tool integrations.

Conclusion

This Claude Code global configuration provides a practical integration scheme for connecting Anthropic’s local coding client to the DeepSeek V4 model series. It preserves the key tuning parameters, including the 1,200,000ms API timeout, the 80% automatic context compression threshold, the max reasoning effort level, and the model alias mapping for Haiku, Sonnet, Opus, reasoning, and subagent tasks.

Its main value lies in three areas. It enables ultra-long-context inference through DeepSeek-V4-Pro[1m]. It improves local system safety through layered command permission rules. It also extends Claude Code into a broader development environment through MCP servers for browser automation, documentation retrieval, game development, and GitHub operations.

For teams that also need centralized API forwarding and shared credential management, an API gateway layer can further simplify operations. In this type of setup, 4sapi can serve as a unified access layer for multi-model API traffic, especially when cost control and stable routing are important considerations.