Release v0.2.1 (What’s new?).
Welcome to claude_desktop_config Documentation¶
claude_desktop_config is a Python library for programmatically managing Claude Desktop’s MCP (Model Context Protocol) server configurations. It provides a simple, Pythonic interface to add, update, and remove MCP servers in the claude_desktop_config.json file without manually editing JSON. The library handles platform-specific configuration paths automatically and ensures safe, atomic updates to maintain configuration integrity.
Usage Examples¶
Functional API - Add or Update an MCP Server
from claude_desktop_config.api import ClaudeDesktopConfig, enable_mcp_server
# Create config instance (auto-detects platform-specific path)
cdc = ClaudeDesktopConfig()
# Read current configuration
config = cdc.read()
# Add or update an MCP server
changed = enable_mcp_server(
config,
name="my-knowledge-base",
settings={
"command": "npx",
"args": ["-y", "@modelcontextprotocol/server-memory"]
}
)
# Write back if changed
if changed:
cdc.write(config)
Functional API - Remove an MCP Server
from claude_desktop_config.api import ClaudeDesktopConfig, disable_mcp_server
cdc = ClaudeDesktopConfig()
config = cdc.read()
# Remove a server (idempotent - no error if doesn't exist)
if disable_mcp_server(config, "my-knowledge-base"):
cdc.write(config)
Enum API - Declarative Server Management
from claude_desktop_config.api import ClaudeDesktopConfig, BaseMcpEnum, Mcp
# Define your MCP servers as an enum
class MyMcpServers(BaseMcpEnum):
filesystem = Mcp(
name="filesystem",
settings={
"command": "npx",
"args": ["-y", "@modelcontextprotocol/server-filesystem", "/home/user/documents"]
}
)
github = Mcp(
name="github",
settings={
"command": "npx",
"args": ["-y", "@modelcontextprotocol/server-github"]
}
)
memory = Mcp(
name="memory",
settings={
"command": "npx",
"args": ["-y", "@modelcontextprotocol/server-memory"]
}
)
# Apply desired state - this will:
# 1. Enable filesystem and github servers
# 2. Disable memory server (if it exists)
cdc = ClaudeDesktopConfig()
MyMcpServers.apply([MyMcpServers.filesystem, MyMcpServers.github], cdc)
Work with Custom Config Path
from pathlib import Path
# Use a custom configuration file path
cdc = ClaudeDesktopConfig(path=Path("/custom/path/config.json"))
# Read current configuration
current_config = cdc.read()
print(current_config)
Batch Operations with Functional API
from claude_desktop_config.api import ClaudeDesktopConfig, enable_mcp_server, disable_mcp_server
cdc = ClaudeDesktopConfig()
config = cdc.read()
# Track if any changes were made
changed = False
# Add multiple MCP servers
servers = {
"filesystem": {
"command": "npx",
"args": ["-y", "@modelcontextprotocol/server-filesystem", "/home/user/documents"]
},
"github": {
"command": "npx",
"args": ["-y", "@modelcontextprotocol/server-github"]
}
}
for name, settings in servers.items():
changed |= enable_mcp_server(config, name, settings)
# Remove unwanted servers
for name in ["old-server", "deprecated-server"]:
changed |= disable_mcp_server(config, name)
# Write once if any changes were made
if changed:
cdc.write(config)
Install¶
claude_desktop_config is released on PyPI, so all you need is to:
$ pip install claude-desktop-config
To upgrade to latest version:
$ pip install --upgrade claude-desktop-config