sheets_check_access

Verify spreadsheet access permissions to determine allowed operations. Input the spreadsheet ID to retrieve detailed access information.

Instructions

Check access permissions for a spreadsheet. Returns information about what operations are allowed.

Input Schema

TableJSON Schema

Name	Required	Description	Default
`spreadsheetId`	Yes	The ID of the spreadsheet to check access for

Implementation Reference

src/tools/check-access.ts:26-110 (handler)

The core handler function that implements the tool logic: parses input, authenticates with Google Sheets API, checks read/write permissions by attempting API calls, handles errors, and returns permission status and recommendations.

export async function handleCheckAccess(input: any) {
  try {
    const { spreadsheetId } = CheckAccessSchema.parse(input);
    const sheets = await getAuthenticatedClient();

    const permissions = {
      canRead: false,
      canWrite: false,
      canShare: false,
      isOwner: false,
      error: null as string | null,
    };

    try {
      // Try to read spreadsheet metadata
      const response = await sheets.spreadsheets.get({
        spreadsheetId,
        fields: 'properties.title,sheets.properties.sheetId,sheets.properties.title',
      });

      permissions.canRead = true;

      // Try to create a test request (but don't execute it) to check write permissions
      try {
        // Test write access by trying to prepare a values update
        await sheets.spreadsheets.values.update(
          {
            spreadsheetId,
            range: 'A1',
            valueInputOption: 'RAW',
            requestBody: {
              values: [['']],
            },
          },
          {
            // Use validateOnly to not actually write
            params: {
              validateOnly: true,
            },
          }
        );
        permissions.canWrite = true;
      } catch (writeError: any) {
        if (writeError.code === 403) {
          permissions.canWrite = false;
        } else if (writeError.code !== 400) {
          permissions.canWrite = true;
        }
      }

      return {
        spreadsheetId,
        title: response.data.properties?.title || 'Unknown',
        permissions,
        sheets:
          response.data.sheets?.map((sheet: any) => ({
            sheetId: sheet.properties?.sheetId,
            title: sheet.properties?.title,
          })) || [],
        recommendation: permissions.canWrite
          ? 'You have full read/write access to this spreadsheet.'
          : 'You have read-only access to this spreadsheet. To write data, the spreadsheet owner needs to grant you Editor permissions.',
      };
    } catch (error: any) {
      if (error.code === 404) {
        permissions.error = 'Spreadsheet not found. Check if the ID is correct.';
      } else if (error.code === 403) {
        permissions.error =
          'Access denied. The spreadsheet needs to be shared with your service account.';
      } else {
        permissions.error = error.message || 'Unknown error occurred';
      }

      return {
        spreadsheetId,
        permissions,
        error: permissions.error,
        recommendation:
          'Share the spreadsheet with your service account email and grant appropriate permissions.',
      };
    }
  } catch (error) {
    return handleError(error);
  }
}

src/tools/check-access.ts:6-24 (schema)

Zod schema for input validation and the Tool definition including name, description, and inputSchema for MCP protocol compliance.

const CheckAccessSchema = z.object({
  spreadsheetId: z.string().describe('The ID of the spreadsheet to check access for'),
});

export const checkAccessTool: Tool = {
  name: 'sheets_check_access',
  description:
    'Check access permissions for a spreadsheet. Returns information about what operations are allowed.',
  inputSchema: {
    type: 'object',
    properties: {
      spreadsheetId: {
        type: 'string',
        description: 'The ID of the spreadsheet to check access for',
      },
    },
    required: ['spreadsheetId'],
  },
};

src/index.ts:33-33 (registration)
Registration of the tool handler in the toolHandlers Map used for executing called tools.
```
['sheets_check_access', tools.handleCheckAccess],
```
src/index.ts:68-68 (registration)
Registration of the tool definition in the allTools array used for listing available tools.
```
tools.checkAccessTool,
```
src/tools/index.ts:19-19 (registration)
Re-export of the tool and handler from check-access module for barrel import in main index.
```
export * from './check-access.js';
```

mcp-gsheets