dev-brewery/claude-agents-mcp

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

Global Configuration

Custom Commands

Project Context

Utilities

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

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

Development

# Watch mode
npm run dev

# Build
npm run build

# Run migration
npm run migrate

# Start production
npm start

License

MIT