blackhawk-mcp

BlackHawkMCP

BlackHawkMCP is an MCP server that connects AI assistants (Claude, Cursor, Copilot) to Google Sheets. It provides a stable, secure bridge to create, read, write, append, list, clear, and inspect spreadsheets programmatically via the Model Context Protocol.

Features

• Create spreadsheets programmatically
• Read and write cell ranges with USER_ENTERED semantics
• Append rows and clear ranges
• List available spreadsheets (Drive readonly scope required)
• Inspect sheet metadata (titles, ids, grid properties)
• OAuth2-based Google authentication with token persistence

Supported Tools

• hello — Basic connectivity test and greeting.
• create_spreadsheet — Create a new Google Spreadsheet with a title.
• read_sheet — Read values from a spreadsheet range.
• write_sheet — Write values to a spreadsheet range (USER_ENTERED).
• append_rows — Append rows to a sheet.
• list_sheets — List spreadsheets accessible to the service account/user (Drive readonly required).
• clear_range — Clear values in a range.
• get_sheet_info — Retrieve sheet metadata for a spreadsheet.
• auth_status — Check current authentication status.

Installation

Global install (recommended for CLI usage):

npm install -g blackhawk-mcp

Run via npx (no install):

npx blackhawk-mcp

Development

npm install
npm run build
npm run dev

Quick Start (OAuth2)

• Create Google OAuth credentials in Google Cloud Console (OAuth Client ID). Add an authorized redirect URI, e.g. http://localhost:3000/oauth2callback.
• Set environment variables (see Configuration).
• Run the server and call auth_status or call a tool that triggers authorize() (first use may prompt to open a browser and authorize).

Configuration (Environment Variables)

• GOOGLE_CLIENT_ID (required) — OAuth Client ID from Google Cloud Console.
• GOOGLE_CLIENT_SECRET (required) — OAuth Client Secret.
• GOOGLE_REDIRECT_URI (optional) — Redirect URI used during OAuth flows. Default: http://localhost:3000/oauth2callback.

Tools Reference

Each tool accepts JSON parameters and returns a JSON response in the MCP content payload. Examples:

• create_spreadsheet parameters: { "title": "My Sheet" }
• read_sheet parameters: { "spreadsheetId": "<id>", "range": "Sheet1!A1:D10" }
• write_sheet parameters: { "spreadsheetId": "<id>", "range": "Sheet1!A1", "values": [["a","b"]] }
• append_rows parameters: { "spreadsheetId": "<id>", "range": "Sheet1!A:B", "values": [["row1col1","row1col2"]] }
• list_sheets parameters: { "pageSize": 100 } (optional)
• clear_range parameters: { "spreadsheetId": "<id>", "range": "Sheet1!A1:B10" }
• get_sheet_info parameters: { "spreadsheetId": "<id>" }
• auth_status parameters: {}

Multi-Client Setup

Claude Desktop

Follow MCP host integration steps in the Claude Desktop client and configure the MCP package `io.github.000safah000-ai/blackhawk-mcp` as a stdio transport.

VS Code

Use the MCP host or extension that supports stdio MCP servers and point it to `blackhawk-mcp` via configure command or npx.

Cursor

Configure Cursor's MCP integration (stdio transport) and supply environment variables in the runtime configuration UI.

CLI

Use `npx blackhawk-mcp` for quick testing or install globally for `blackhawk-mcp` CLI execution.

Commercial License

BlackHawkMCP is proprietary. Personal, non-commercial evaluation is permitted for up to 30 days. Production or commercial use requires a purchased commercial license.

Purchase a license at: https://gumroad.com/placeholder-license-url

Support

• Discord: discord.gg/sC6jvbtrYr
• Contact: 7sf5 or .1xe

Author

SaFaH (.1xe)