Queen MCP Server

MCP server for Queen Claude autonomous development system. Provides AI agents with structured database access for project management, task coordination, and knowledge storage.

What is Queen MCP?

Queen MCP server gives Claude Code (and other AI agents) direct access to the Queen Claude database through the Model Context Protocol. This enables autonomous development where AI agents can manage tasks, store knowledge, and coordinate work without human intervention.

Features

Project Context Management

• get_project_context - Get complete project overview, critical docs, and important memories

Task Management

• get_available_tasks - Find tasks ready to work on
• create_task - Create new development tasks with requirements and expected results
• update_task_progress - Update task status, progress, and time spent
• get_task_details - Get complete task information including dependencies

Knowledge Management

• search_memory - Search stored patterns, decisions, and knowledge
• store_memory - Store important knowledge for future reference

Problem Tracking

• report_problem - Log issues encountered during development
• get_similar_problems - Find previously solved similar issues
• solve_problem - Mark problems as solved with solution details

Utilities

• query_database - Execute raw SQL queries (SELECT only for safety)
• get_agent_status - Get current agent session status
• update_agent_activity - Update current agent activity and progress

Installation

npm install -g queen-mcp

Or for local development:

git clone <repository>
cd queen-mcp
npm install
npm run build
npm link

Usage

Prerequisites

1. Project must be initialized with Queen Claude:

cd your-project
npx queen-claude-init

2. MCP server automatically discovers .queen/database.db in current working directory

Claude Code Integration

The MCP server is automatically available in Claude Code when installed. No manual setup required.

Example usage in Claude Code:

// Get project context when joining a project
const context = await mcp.call('get_project_context');

// Find work to do
const tasks = await mcp.call('get_available_tasks');

// Start working on a task
await mcp.call('update_agent_activity', {
  activity: 'Implementing user authentication',
  current_file: 'src/components/auth/LoginForm.tsx'
});

// Store important knowledge
await mcp.call('store_memory', {
  title: 'React Hook Pattern',
  content: 'Always include dependencies in useEffect array',
  tags: ['react', 'hooks'],
  importance: 'critical',
  memory_type: 'important_pattern'
});

Database Auto-Discovery

The MCP server automatically finds the Queen database:

1. Looks for: <current-working-directory>/.queen/database.db
2. Validates: Database exists and has required tables
3. Returns helpful errors: If not initialized or corrupted

Error Handling

All tools return helpful error messages:

{
  "error": "Queen Claude not found. Run 'npx queen-claude-init' to initialize this project."
}

Common errors:

• Not initialized: .queen directory doesn't exist
• Corrupted database: Missing required tables
• Invalid task ID: Task not found
• SQL errors: Query execution failures

Real-Time Updates

When database changes occur, the MCP server:

1. Updates .queen/last-update file with timestamp
2. Dashboard (separate web app) watches this file for real-time updates
3. Perfect isolation - each project has its own change file

Development

# Build TypeScript
npm run build

# Development mode (watch)
npm run dev

# Test the server
npm test

Tool Reference

Project Context

get_project_context()
// Returns: { project: {...}, critical_docs: [...], important_memories: [...] }

Task Management

get_available_tasks(status_filter?)
// Returns: Array<TaskSummary>

create_task(name, requirements, files, expected_results, estimated_hours?)
// Returns: { task_id: number }

update_task_progress(task_id, status, progress_percentage?, actual_hours?, notes?)
// Returns: { success: boolean }

get_task_details(task_id)
// Returns: TaskSummary with full details

Knowledge

search_memory(query, tags?, importance_level?)
// Returns: Array<MemorySearchResult>

store_memory(title, content, tags, importance, memory_type, context?)
// Returns: { memory_id: number }

Problem Tracking

report_problem(description, related_files?, severity?)
// Returns: { problem_id: number }

get_similar_problems(description)
// Returns: Array<SimilarProblemResult>

solve_problem(problem_id, solution)
// Returns: { success: boolean }

Utilities

query_database(sql, params?)
// Returns: Array<any> (SELECT queries only)

get_agent_status()
// Returns: AgentStatusResponse

update_agent_activity(activity, current_file?, progress_detail?, task_id?)
// Returns: { success: boolean }

Philosophy

Queen MCP server enables autonomous development by giving AI agents:

• Complete project context when joining a project
• Structured task management with clear requirements and expected results
• Knowledge continuity through memory and problem-solution tracking
• Coordination capabilities for multi-agent parallel development

"Human sets prompt → goes to bed → LLM handles everything" ✨

Requirements

• Node.js 18.0 or later
• Queen Claude initialized project (.queen directory with database)
• Compatible with Claude Code MCP integration

License

MIT

Part of the Queen Claude ecosystem - transforming development through autonomous AI collaboration.