Jules MCP Server

TypeScript-based Model Context Protocol (MCP) server for orchestrating multiple Jules AI instances with comprehensive code generation, bug fixing, and review capabilities.

🚀 Features

Core Capabilities

• Multi-Instance Orchestration: Create and manage multiple Jules workers simultaneously
• Real-Time Activity Monitoring: Track worker progress and status updates
• Plan Approval Flow: Review and approve Jules-generated plans before execution
• Direct Worker Communication: Send messages between workers for coordination
• Shared Memory System: Store and retrieve data across worker sessions
• Git Integration: Branch creation and merging for staged orchestration workflow

MCP Protocol Compliance

• 3 Core Tools: jules_create_worker, jules_send_message, jules_get_activities
• ESM Module Support: Modern JavaScript module system compatibility
• Zod Schema Validation: Comprehensive input validation and error handling
• TypeScript Implementation: Full type safety and modern development practices

Quick Start

Prerequisites

• Node.js 18+
• Jules API key

Installation via npx (Recommended)

# Install and run directly
npx jules-mcp

# Or install globally
npm install -g jules-mcp
jules-mcp

Local Development

# Clone repository
git clone https://github.com/access_aipro/jules-mcp-npx
cd jules-mcp

# Install dependencies
npm install

# Set up environment
export JULES_API_KEY="your-api-key-here"

# Start development server
npm run dev

# Build for production
npm run build
npm start

Configuration

Environment Variables

# Required
JULES_API_KEY=your-api-key-here

# Optional
SERVICE_PORT=8085                    # Server port
LOG_LEVEL=INFO                      # Logging level
JULES_API_BASE_URL=https://jules.googleapis.com  # API endpoint
MAX_COST_PER_HOUR=10.00             # Cost limit per hour
DAILY_COST_LIMIT=100.00             # Daily cost limit
CACHE_TTL=3600                      # Cache time-to-live (seconds)
RATE_LIMIT_REQUESTS=60              # Requests per minute
CODE_VALIDATION_ENABLED=true        # Enable code validation
COST_TRACKING_ENABLED=true          # Enable cost tracking

Get your API key from: https://jules.google.com/settings#api

MCP Client Configuration

Add to your claude_desktop_config.json:

{
  "mcpServers": {
    "jules-orchestrator": {
      "command": "npx",
      "args": ["jules-mcp"]
    }
  }
}

MCP Tools & Resources

🛠️ MCP Tools

• jules_create_worker - Create Jules AI workers for specific implementation tasks (supports Roles: Maestro, Crew, Evaluator)
• jules_send_direct_message - Send direct messages between workers
• jules_estimate_work - Create an Evaluator worker for task estimation
• jules_store_memory - Store shared memory values
• jules_read_memory - Read shared memory values
• jules_create_branch - Create a new git branch (essential for Staged Orchestration)
• jules_merge_branch - Merge a feature branch into a target branch
• jules_list_branches - List all local branches
• jules_generate_code - Generate code for specific requirements with context awareness
• jules_fix_bug - Analyze and fix bugs in existing code
• jules_review_code - Comprehensive code review with security and quality assessment
• jules_get_status - Check worker status and progress

📚 MCP Resources

• jules_documentation:// - Comprehensive documentation for all features
• jules_templates:// - Pre-built templates for common development patterns
• jules_examples:// - Real-world examples and implementation patterns
• workers://all - View all active workers
• worker://{session_id}/status - Individual worker status

Usage Examples

Basic Code Generation

# Generate a React component
result = await jules_mcp.call_tool("jules_generate_code", {
    "prompt": "Create a React component for user login form with TypeScript",
    "language": "typescript",
    "context": {
        "framework": "react",
        "styling": "tailwind",
        "validation": "yup"
    }
})

Bug Fixing

# Fix a memory leak in Node.js application
result = await jules_mcp.call_tool("jules_fix_bug", {
    "code": "existing-code-with-leak.js",
    "error_description": "Memory usage increases over time",
    "expected_behavior": "Constant memory usage"
})

Code Review

# Review Python API endpoint
result = await jules_mcp.call_tool("jules_review_code", {
    "code": "api-endpoint.py",
    "language": "python",
    "focus_areas": ["security", "performance", "error_handling"]
})

Claude + Jules Workflow

1. Planning Phase (Claude)

Claude creates detailed specifications and planning documents using the knowledge base:

## Feature: User Authentication System

### Requirements
- Email/password authentication
- JWT token management
- Session handling
- Password reset functionality

### Technical Specifications
- Use bcrypt for password hashing
- JWT with 15-minute expiration
- Refresh token mechanism
- Rate limiting for login attempts

2. Implementation Phase (Jules)

Jules implements based on Claude's specifications:

await jules_mcp.call_tool("jules_create_worker", {
    "task_description": planning_document,
    "source": "current-repository",
    "title": "User Authentication Implementation"
})

3. Review & Integration

Both Claude and Jules collaborate on code quality and integration.

Knowledge Base

The Jules MCP server includes a comprehensive knowledge base with:

• 250+ Community-Curated Prompts: From the Google Jules Awesome List
• 20+ Development Categories: Web, mobile, backend, DevOps, security
• Real-World Examples: Production-tested patterns and implementations
• Performance Benchmarks: Optimization strategies and best practices

Access the knowledge base through:

• JULES_KNOWLEDGE_BASE.md - Complete prompt library
• MCP tools for prompt recommendations
• Context-aware suggestions based on project type

Testing

# Run comprehensive test suite
npm test

# Build and type check
npm run build

# Lint code
npm run lint

# Development with hot reload
npm run dev

Monitoring & Analytics

Health Checks

# Basic health
GET /health

# Detailed health with Jules API status
GET /health/detailed

# Cost tracking status
GET /health/cost-tracker

Metrics Available

• Request Volume: API calls per minute/hour
• Cost Tracking: Real-time cost accumulation
• Cache Performance: Hit rates and efficiency
• Error Rates: Types and frequency of errors
• Response Times: Latency percentiles

Status

✅ Production Ready - Enhanced implementation with knowledge base integration ✅ Google Jules API - Full API integration with cost optimization ✅ MCP Protocol - Complete Model Context Protocol compliance ✅ Knowledge Base - 250+ community-curated prompts integrated ✅ Performance - 11,981+ activities/second capability demonstrated ✅ Enterprise Features - Cost tracking, security, monitoring

Architecture

• src/index.ts - Main MCP server entry point with tool registration
• src/jules-client.ts - Jules API client with TypeScript types
• src/worker-manager.ts - Worker orchestration and management
• dist/ - Compiled JavaScript output for distribution
• package.json - Node.js package configuration and dependencies

Built with: @modelcontextprotocol/sdk, TypeScript, axios, zod

---

Version: 1.0.0 | Last Updated: 2026-01-24 | Support: Enterprise Available