Jules MCP Server

Instructions

Implementation Reference

• src/mcp/tools.ts:166-199 (handler)

  Executes the create_coding_task tool by validating input, checking repository allowlist, creating a Jules session with specified parameters, and returning session details including monitor URL.

  async createCodingTask(
    args: z.infer<typeof CreateTaskSchema>
  ): Promise<string> {
    return this.executeWithErrorHandling(async () => {
      // SECURITY: Validate repository allowlist
      RepositoryValidator.validateRepository(args.source);
  
      const session = await this.client.createSession({
        prompt: args.prompt,
        sourceContext: {
          source: args.source,
          githubRepoContext: {
            startingBranch: args.branch,
          },
        },
        automationMode: args.auto_create_pr
          ? 'AUTO_CREATE_PR'
          : 'AUTOMATION_MODE_UNSPECIFIED',
        requirePlanApproval: args.require_plan_approval,
        title: args.title,
      });
  
      const statusMsg = args.require_plan_approval
        ? 'Session created and waiting for plan approval. Use jules://sessions/{id}/full to review the plan, then call manage_session with action=approve_plan.'
        : 'Session created and executing automatically.';
  
      return {
        sessionId: session.id,
        state: session.state,
        message: statusMsg,
        monitorUrl: `https://jules.google/sessions/${session.id}`,
      };
    });
  }

• src/mcp/tools.ts:15-53 (schema)

  Zod input validation schema for the create_coding_task tool parameters.

  export const CreateTaskSchema = z.object({
    prompt: z
      .string()
      .min(10, 'Prompt must be at least 10 characters')
      .max(10000, 'Prompt must not exceed 10,000 characters')
      .refine((val) => val.trim().length > 0, 'Prompt cannot be empty or whitespace only')
      .describe(
        'Natural language instruction for the coding task. Be specific about files, goals, and constraints.'
      ),
    source: z
      .string()
      .regex(
        /^sources\/github\/[\w-]+\/[\w-]+$/,
        'Source must be in format sources/github/owner/repo'
      )
      .describe(
        'Repository resource name (format: sources/github/owner/repo). Check jules://sources resource first.'
      ),
    branch: z
      .string()
      .regex(/^[\w/-]+$/, 'Branch name contains invalid characters')
      .default('main')
      .describe('Git branch to base changes on'),
    auto_create_pr: z
      .boolean()
      .default(true)
      .describe('If true, automatically creates a Pull Request upon completion'),
    require_plan_approval: z
      .boolean()
      .default(false)
      .describe(
        'If true, pauses at AWAITING_PLAN_APPROVAL state for manual review'
      ),
    title: z
      .string()
      .max(200, 'Title must not exceed 200 characters')
      .optional()
      .describe('Optional human-readable session title'),
  });

• src/index.ts:184-224 (registration)

  Registration of the create_coding_task tool in the ListToolsRequestSchema response, including name, description, and input schema.

  {
    name: 'create_coding_task',
    description:
      'Creates a new Jules coding session. Returns immediately with a session ID. Monitor progress via jules://sessions/{id}/full resource.',
    inputSchema: {
      type: 'object',
      properties: {
        prompt: {
          type: 'string',
          description:
            'Natural language instruction for the coding task',
        },
        source: {
          type: 'string',
          description:
            'Repository resource name (sources/github/owner/repo)',
        },
        branch: {
          type: 'string',
          description: 'Git branch to base changes on',
          default: 'main',
        },
        auto_create_pr: {
          type: 'boolean',
          description:
            'Automatically create Pull Request upon completion',
          default: true,
        },
        require_plan_approval: {
          type: 'boolean',
          description: 'Pause for manual plan review',
          default: false,
        },
        title: {
          type: 'string',
          description: 'Optional session title',
        },
      },
      required: ['prompt', 'source'],
    },
  },

• src/index.ts:316-319 (registration)

  Dispatch logic in CallToolRequestSchema handler that validates arguments using CreateTaskSchema and calls the tool handler.

  case 'create_coding_task': {
    const validated = CreateTaskSchema.parse(args);
    result = await this.tools.createCodingTask(validated);
    break;