Claude Agents MCP Server

A centralized MCP (Model Context Protocol) server for managing Claude agent definitions, configurations, and custom commands across multiple devices without file synchronization issues.

Why This Exists

When syncing Claude configuration files via Nextcloud (or other sync services), file locking issues occur because:

• Claude Code holds locks on history.jsonl, .update.lock, and IDE files
• Multiple devices competing for the same files cause sync conflicts
• Session data constantly changes, creating sync storms

This MCP server solves these problems by:

• Serving configurations via HTTP/stdio (no file locks)
• Centralizing agent definitions in a SQLite database
• Providing version control and conflict resolution
• Enabling live updates across all connected Claude sessions

Quick Start

Local Development

# Install dependencies
npm install

# Run migration to import existing configs
npm run migrate -- --source "G:/Nextcloud"

# Start development server
npm run dev

Docker Deployment

# Build and run
docker-compose up -d

# View logs
docker-compose logs -f claude-agents-mcp

Configure Claude Code

IMPORTANT: MCP servers are registered in your global Claude config file:

• Linux/Mac: ~/.claude.json
• Windows: C:\Users\<username>\.claude.json

Add the MCP server configuration to this file (Claude Code may auto-add it when you first build the server):

{
  "mcpServers": {
    "claude-agents": {
      "command": "node",
      "args": ["/absolute/path/to/claude-agents-mcp/dist/index.js"],
      "env": {
        "CONFIG_DATA_PATH": "/absolute/path/to/claude-agents-mcp/data"
      }
    }
  }
}

Note:

• Use absolute paths to the built server
• The server runs via stdio (starts when Claude Code starts, stops when it exits)
• It does NOT run as a background service - data persists in SQLite, process does not

Or for network access via HTTP API:

{
  "mcpServers": {
    "claude-agents": {
      "url": "http://localhost:8765"
    }
  }
}

MCP Tools

Agent Management

Tool	Description
list_agents	List all agents, optionally filtered by category
get_agent	Retrieve a specific agent definition
publish_agent	Create or update an agent
delete_agent	Remove an agent
search_agents	Search agents by name or content

Global Configuration

Tool	Description
get_global_config	Get CLAUDE.md, session_init, or constraints
set_global_config	Update global configuration

Custom Commands

Tool	Description
list_commands	List all custom slash commands
get_command	Retrieve a command definition
publish_command	Create or update a command
delete_command	Remove a command

Project Context

Tool	Description
get_project_context	Get project-specific settings
set_project_context	Save project context

Utilities

Tool	Description
get_sync_history	View recent changes

HTTP API Endpoints

When running the API server (src/api.ts):

GET    /api/agents              # List all agents
GET    /api/agents/:category    # List agents by category
GET    /api/agent/:name         # Get agent content
POST   /api/agent               # Create/update agent
DELETE /api/agent/:name         # Delete agent

GET    /api/config/:type        # Get global config
POST   /api/config/:type        # Set global config

GET    /api/commands            # List commands
GET    /api/command/:name       # Get command
POST   /api/command             # Create/update command
DELETE /api/command/:name       # Delete command

GET    /api/project/:id         # Get project context
POST   /api/project/:id         # Set project context

GET    /api/search?q=query      # Search agents
GET    /api/history?limit=50    # Sync history
GET    /health                  # Health check

Agent Categories

Category	Description
roles	Role-based agents (SeniorArchitect, etc.)
contexts	Context-specific prompts (GeneralCoding, etc.)
tasks	Task-oriented agents (Refactor, Review, etc.)
community	Community-contributed agents
brahma	Brahma-series specialized agents

Migration

Import existing configurations from Nextcloud:

npm run migrate -- --source "G:/Nextcloud" --data "./data"

This will import:

• All agent definitions from AgentConfigs/.claude/agents/
• Agent templates from AgentPrompts/
• Global configs (CLAUDE.md, SESSION_INIT.md, AGENT_CONSTRAINTS.md)
• Custom commands from .claude/commands/

Directory Structure

claude-agents-mcp/
├── src/
│   ├── index.ts      # MCP server (stdio)
│   ├── api.ts        # HTTP API wrapper
│   ├── db.ts         # SQLite storage layer
│   └── migrate.ts    # Migration script
├── data/
│   └── config.db     # SQLite database
├── docker-compose.yml
├── Dockerfile
└── Dockerfile.api

Environment Variables

Variable	Default	Description
CONFIG_DATA_PATH	./data	Path to data directory
API_PORT	8765	HTTP API port
NODE_ENV	development	Environment mode

Development

# Watch mode
npm run dev

# Build
npm run build

# Run migration
npm run migrate

# Start production
npm start

License

MIT