# 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
```bash
# Install dependencies
npm install
# Run migration to import existing configs
npm run migrate -- --source "G:/Nextcloud"
# Start development server
npm run dev
```
### Docker Deployment
```bash
# 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):
```json
{
"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:
```json
{
"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:
```bash
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
```bash
# Watch mode
npm run dev
# Build
npm run build
# Run migration
npm run migrate
# Start production
npm start
```
## License
MIT
