使用说明

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

Architecture

Claude Code (any machine)
    |
    | MCP protocol (stdio)
    v
claude-agents-mcp server
    |
    +-- SQLite store (agents, configs, metadata)
    |     single-writer, no file locks to fight sync clients
    |
    +-- Export layer
          writes agent definitions back out as files
          when a target machine needs them on disk

One writer (SQLite) replaces many synced files. Sync services stop fighting Claude Code over file locks because the canonical state is no longer a directory of loose files; machines pull from the server and export what they need locally.

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