{"id":28824529,"url":"https://github.com/tumf/fastmcp-gsuite","last_synced_at":"2026-04-04T11:33:27.138Z","repository":{"id":288103015,"uuid":"966821918","full_name":"tumf/fastmcp-gsuite","owner":"tumf","description":"MCP server for Gmail, Google Calendar, and Google Drive integration using fastmcp. Supports multiple accounts, email management, calendar events, and file operations.","archived":false,"fork":false,"pushed_at":"2026-03-31T10:16:46.000Z","size":576,"stargazers_count":9,"open_issues_count":1,"forks_count":3,"subscribers_count":1,"default_branch":"main","last_synced_at":"2026-03-31T12:19:27.303Z","etag":null,"topics":["claude","fastmcp","gmail","google-calendar","google-drive","google-workspace","mcp","mcp-server","python"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/tumf.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":"AGENTS.md","dco":null,"cla":null}},"created_at":"2025-04-15T14:01:16.000Z","updated_at":"2026-03-31T10:16:52.000Z","dependencies_parsed_at":null,"dependency_job_id":"196316bc-16fa-4098-89f9-5bf6b1e3525e","html_url":"https://github.com/tumf/fastmcp-gsuite","commit_stats":null,"previous_names":["tumf/fastmcp-gsuite"],"tags_count":2,"template":false,"template_full_name":null,"purl":"pkg:github/tumf/fastmcp-gsuite","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tumf%2Ffastmcp-gsuite","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tumf%2Ffastmcp-gsuite/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tumf%2Ffastmcp-gsuite/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tumf%2Ffastmcp-gsuite/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/tumf","download_url":"https://codeload.github.com/tumf/fastmcp-gsuite/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tumf%2Ffastmcp-gsuite/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":31398226,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-04T10:20:44.708Z","status":"ssl_error","status_checked_at":"2026-04-04T10:20:06.846Z","response_time":60,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["claude","fastmcp","gmail","google-calendar","google-drive","google-workspace","mcp","mcp-server","python"],"created_at":"2025-06-19T01:34:05.545Z","updated_at":"2026-04-04T11:33:27.121Z","avatar_url":"https://github.com/tumf.png","language":"Python","funding_links":[],"categories":["📦 Other","☁️ Cloud Platforms \u0026 Services"],"sub_categories":[],"readme":"# fastmcp-gsuite MCP server (using fastmcp)\n\n[![codecov](https://codecov.io/gh/tumf/fastmcp-gsuite/branch/main/graph/badge.svg)](https://codecov.io/gh/tumf/fastmcp-gsuite)\n\nMCP server to interact with Google products, rewritten using the `fastmcp` library.\n\nThis project is a fork of [mcp-gsuite](https://github.com/MarkusPfundstein/mcp-gsuite).\n\n* [My tech blog article](https://blog.tumf.dev/posts/diary/2025/12/31/fastmcp-gsuite-2-weeks-update/)\n\n## Example prompts\n\nRight now, this MCP server supports Gmail and Calendar integration with the following capabilities:\n\n1. General\n* Multiple google accounts\n\n2. Gmail\n* Get your Gmail user information\n* Query emails with flexible search (e.g., unread, from specific senders, date ranges, with attachments)\n* Retrieve complete email content by ID\n* Create new draft emails with recipients, subject, body and CC options\n* Delete draft emails\n* Reply to existing emails (can either send immediately or save as draft)\n* Retrieve multiple emails at once by their IDs.\n* Save multiple attachments from emails to your local system.\n\n3. Calendar\n* Manage multiple calendars\n* Get calendar events within specified time ranges\n* Create calendar events with:\n  + Title, start/end times\n  + Optional location and description\n  + Optional attendees\n  + Custom timezone support\n  + Notification preferences\n* Delete calendar events\n\nExample prompts you can try:\n\n* Retrieve my latest unread messages\n* Search my emails from the Scrum Master\n* Retrieve all emails from accounting\n* Take the email about ABC and summarize it\n* Write a nice response to Alice's last email and upload a draft.\n* Reply to Bob's email with a Thank you note. Store it as draft\n\n* What do I have on my agenda tomorrow?\n* Check my private account's Family agenda for next week\n* I need to plan an event with Tim for 2hrs next week. Suggest some time slots.\n\n## Quickstart\n\n### Install\n\n#### Quick Setup (Recommended)\n\nThe easiest way to set up authentication is using the interactive setup command:\n\n```bash\n# Install the package\npip install fastmcp-gsuite\n# or with uv\nuv pip install fastmcp-gsuite\n\n# Run interactive setup\nuv run fastmcp-gsuite-setup\n```\n\n**Prerequisites:**\n- Create OAuth2 credentials in [Google Cloud Console](https://console.cloud.google.com/apis/credentials)\n  - Select \"Desktop app\" as application type\n  - Enable Gmail API, Google Calendar API, and Google Drive API\n\nThe setup wizard will guide you through:\n1. Entering your Google OAuth2 Client ID and Client Secret\n2. Authorizing your Google account(s) in browser\n3. Copying the authorization code from browser back to terminal\n4. Automatically creating all necessary configuration files\n\n**Additional Commands:**\n```bash\n# Add another Google account\nuv run fastmcp-gsuite-setup --add-account\n\n# List configured accounts\nuv run fastmcp-gsuite-setup --list\n\n# Remove an account\nuv run fastmcp-gsuite-setup --remove-account user@example.com\n```\n\n#### Manual Setup (Advanced)\n\n\u003cdetails\u003e\n  \u003csummary\u003eClick to expand manual setup instructions\u003c/summary\u003e\n\nGoogle Workspace (G Suite) APIs require OAuth2 authorization. Follow these steps to set up authentication manually:\n\n1. Create OAuth2 Credentials:\n   - Go to the [Google Cloud Console](https://console.cloud.google.com/)\n   - Create a new project or select an existing one\n   - Enable the Gmail API, Google Calendar API, and Google Drive API for your project\n   - Go to \"Credentials\" → \"Create Credentials\" → \"OAuth client ID\"\n   - Select \"Desktop app\" as the application type\n   - Configure the OAuth consent screen with required information\n   - **Note**: For desktop/CLI applications, the redirect URI `urn:ietf:wg:oauth:2.0:oob` will be used automatically\n\n2. Required OAuth2 Scopes:\n\n```json\n   [\n     \"openid\",\n     \"https://mail.google.com/\",\n     \"https://www.googleapis.com/auth/calendar\",\n     \"https://www.googleapis.com/auth/drive\",\n     \"https://www.googleapis.com/auth/userinfo.email\"\n   ]\n```\n\n3. Create a `.gauth.json` in your working directory:\n\n```json\n{\n    \"installed\": {\n        \"client_id\": \"$your_client_id\",\n        \"client_secret\": \"$your_client_secret\",\n        \"redirect_uris\": [\"urn:ietf:wg:oauth:2.0:oob\", \"http://localhost\"],\n        \"auth_uri\": \"https://accounts.google.com/o/oauth2/auth\",\n        \"token_uri\": \"https://oauth2.googleapis.com/token\"\n    }\n}\n```\n\n**Note**: \n- Use `\"installed\"` for Desktop app credentials (recommended)\n- Alternatively, `\"web\"` format also works with this library\n- `urn:ietf:wg:oauth:2.0:oob` is the Out-of-Band (OOB) redirect URI\n- Google will display the authorization code in the browser for you to copy and paste\n\n4. Create a `.accounts.json` file with account information:\n\n```json\n{\n    \"accounts\": [\n        {\n            \"email\": \"alice@bob.com\",\n            \"account_type\": \"personal\",\n            \"extra_info\": \"Additional info that you want to tell Claude: E.g. 'Contains Family Calendar'\"\n        }\n    ]\n}\n```\n\nYou can specify multiple accounts. Make sure they have access in your Google Auth app. The `extra_info` field is especially interesting as you can add info here that you want to tell the AI about the account (e.g. whether it has a specific agenda).\n\n5. Run the authentication script to generate credentials:\n\n```bash\n# Set environment variables\nexport GOOGLE_ACCOUNT_EMAIL=\"your-email@example.com\"\nexport GOOGLE_CLIENT_ID=\"your-client-id\"\nexport GOOGLE_CLIENT_SECRET=\"your-client-secret\"\n\n# Run the script\nuv run python scripts/get_refresh_token.py\n```\n\nThis will open a browser for authorization and create `.oauth2.{email}.json` credential files.\n\n\u003c/details\u003e\n\n#### Claude Desktop\n\nOn MacOS: `~/Library/Application\\ Support/Claude/claude_desktop_config.json`\n\nOn Windows: `%APPDATA%/Claude/claude_desktop_config.json`\n\n\u003cdetails\u003e\n  \u003csummary\u003eDevelopment/Unpublished Servers Configuration\u003c/summary\u003e\n\n```json\n{\n  \"mcpServers\": {\n    \"gsuite\": {\n      \"command\": \"uv\",\n      \"args\": [\n        \"--directory\",\n        \"\u003cdir_to\u003e/fastmcp-gsuite\",\n        \"run\",\n        \"fastmcp-gsuite\"\n      ]\n    }\n  }\n}\n```\n\nNote: Configuration is now primarily handled via environment variables or a `.env` file in the working directory, using `pydantic-settings` . See the Configuration Options section below.\n\n```json\n{\n  \"mcpServers\": {\n    \"fastmcp-gsuite\": {\n      \"command\": \"uv\",\n      \"args\": [\n        \"--directory\",\n        \"\u003cdir_to\u003e/fastmcp-gsuite\",\n        \"run\",\n        \"fastmcp-gsuite\" # Use the new entry point\n        # Configuration via .env or environment variables is preferred now\n      ]\n    }\n  }\n}\n```\n\n\u003c/details\u003e\n\n\u003cdetails\u003e\n  \u003csummary\u003ePublished Servers Configuration\u003c/summary\u003e\n\n```json\n{\n  \"mcpServers\": {\n    \"fastmcp-gsuite\": {\n      \"command\": \"uvx\",\n      \"args\": [\n        \"fastmcp-gsuite\" # Use the new entry point\n        # Configuration via .env or environment variables is preferred now\n      ]\n    }\n  }\n}\n```\n\n\u003c/details\u003e\n\n### Configuration Options (via `.env` file or Environment Variables)\n\nConfiguration is now managed using `pydantic-settings` . Create a `.env` file in the directory where you run the server, or set environment variables:\n\n* `GAUTH_FILE`: Path to the `.gauth.json` file containing OAuth2 client configuration. Default: `./.gauth.json`\n* `ACCOUNTS_FILE`: Path to the `.accounts.json` file containing Google account information. Default: `./.accounts.json`\n* `CREDENTIALS_DIR`: Directory to store the generated `.oauth2.{email}.json` credential files. Default: `.` (current directory)\n\nExample `.env` file:\n\n```dotenv\nGAUTH_FILE=/path/to/your/.gauth.json\nACCOUNTS_FILE=/path/to/your/.accounts.json\nCREDENTIALS_DIR=/path/to/your/credentials\n```\n\nThis allows for flexible configuration without command-line arguments when running the server.\n\n### Troubleshooting Setup\n\n**Problem: \"No refresh token received\"**\n- **Cause**: You may have already authorized the app previously\n- **Solution**: Go to https://myaccount.google.com/permissions and revoke access, then try setup again\n\n**Problem: \"Browser doesn't open automatically\"**\n- **Solution**: Copy the authorization URL displayed in the terminal and open it manually in your browser\n\n**Problem: \"Redirect URI mismatch\" error**\n- **Cause**: Google Cloud Console has wrong redirect URI configured\n- **Solution**: In Google Cloud Console, ensure your OAuth client is configured as \"Desktop app\" type. Desktop apps automatically use `urn:ietf:wg:oauth:2.0:oob` as the redirect URI\n\n**Problem: \"Permission denied when creating .gauth.json\"**\n- **Cause**: Insufficient write permissions in current directory\n- **Solution**: Run setup in a directory where you have write permissions, or use `GAUTH_FILE` environment variable to specify a different location\n\n**Problem: \"Account already exists\" when adding account**\n- **Solution**: Use `--remove-account` to remove the old account first, or choose to overwrite when prompted\n\n**Problem: Setup works but MCP server can't find credentials**\n- **Solution**: Ensure you're running the MCP server from the same directory where you ran setup, or set `GAUTH_FILE`, `ACCOUNTS_FILE`, and `CREDENTIALS_DIR` environment variables to point to the correct locations\n\nFor more help, see the [GitHub Issues](https://github.com/tumf/fastmcp-gsuite/issues).\n\n## Development\n\n### Building and Publishing\n\nTo prepare the package for distribution:\n\n1. Sync dependencies and update lockfile:\n\n```bash\nuv sync\n```\n\n2. Build package distributions:\n\n```bash\nuv build\n```\n\nThis will create source and wheel distributions in the `dist/` directory.\n\n3. Publish to PyPI:\n\n```bash\nuv publish\n```\n\nNote: You'll need to set PyPI credentials via environment variables or command flags:\n* Token: `--token` or `UV_PUBLISH_TOKEN`\n* Or username/password: `--username`/`UV_PUBLISH_USERNAME` and `--password`/`UV_PUBLISH_PASSWORD`\n\n### Automatic PyPI Publishing with Tag Push\n\nThis project is configured to automatically publish to PyPI when a tag is pushed to the repository. The publishing process is handled by a GitHub Actions workflow.\n\nTo publish a new version:\n\n1. Update the version in `pyproject.toml`\n2. Commit the changes\n3. Tag the commit with a version tag (e.g., `v0.4.2`)\n4. Push the tag to GitHub\n\n```bash\n# Example workflow to release a new version\ngit add pyproject.toml\ngit commit -m \"Bump version to 0.4.2\"\ngit tag -a v0.4.2 -m \"Version 0.4.2\"\ngit push \u0026\u0026 git push --tags\n```\n\nThe GitHub Actions workflow will automatically build and publish the package to PyPI. Make sure to set the following secrets in your GitHub repository:\n\n* `PYPI_API_TOKEN`: Your PyPI API token\n\nYou can also use the version bumping commands in the Makefile:\n\n```bash\n# Bump patch version (0.4.1 -\u003e 0.4.2)\nmake bump-patch\n\n# Bump minor version (0.4.1 -\u003e 0.5.0)\nmake bump-minor\n\n# Bump major version (0.4.1 -\u003e 1.0.0)\nmake bump-major\n```\n\n### Debugging\n\nSince MCP servers run over stdio, debugging can be challenging. For the best debugging\nexperience, we strongly recommend using the [MCP Inspector](https://github.com/modelcontextprotocol/inspector).\n\nYou can launch the MCP Inspector via [ `npm` ](https://docs.npmjs.com/downloading-and-installing-node-js-and-npm) with this command:\n\n```bash\nnpx @modelcontextprotocol/inspector uv --directory /path/to/fastmcp-gsuite run fastmcp-gsuite\n```\n\nUpon launching, the Inspector will display a URL that you can access in your browser to begin debugging.\n\nYou can also watch the server logs with this command:\n\n```bash\ntail -n 20 -f ~/Library/Logs/Claude/mcp-server-fastmcp-gsuite.log # Log filename might change based on the server name\n```\n\n## E2E Testing\n\n### Standard E2E Tests\n\nTo run the standard E2E tests, you need to set up the necessary environment variables with valid Google credentials:\n\n```bash\n# Make sure valid Google credentials are set in your environment variables\ndotenvx run -f .env.local -- uv run make e2e-tests\n```\n\nThese tests use the Google API libraries directly to authenticate and test the functionality.\n\n### MCP-Based E2E Tests\n\nThere are also MCP-based E2E tests that test the functionality through the MCP protocol, simulating how Claude or other clients would interact with the MCP server:\n\n```bash\n# Specify the environment file containing your Google credentials\nmake mcp-e2e-tests ENV_FILE=.env.local\n```\n\nThis will run tests that:\n1. Start the MCP G-Suite server\n2. Connect to it using the chuk-mcp client\n3. Test various tools like Gmail message listing and Calendar event retrieval\n\nThe environment file should contain the following variables:\n- `GSUITE_CREDENTIALS_JSON` - Base64 encoded JSON credentials\n- `GOOGLE_ACCOUNT_EMAIL` - Your Google account email\n- `GOOGLE_PROJECT_ID` - Your Google Cloud project ID\n- `GOOGLE_CLIENT_ID` - Your OAuth client ID\n- `GOOGLE_CLIENT_SECRET` - Your OAuth client secret\n\nBoth types of E2E tests are excluded from CI pipelines and should only be run locally with valid credentials.\n\n### E2E Test Execution Guide\n\nThis project implements end-to-end (E2E) tests using real Google accounts. You can run the E2E tests using the following steps.\n\n#### Prerequisites\n\nTo run E2E tests, you need:\n\n1. A `.env.local` file with the following environment variables:\n   - `GSUITE_CREDENTIALS_JSON` : Base64 encoded Google credentials\n   - `GOOGLE_ACCOUNT_EMAIL` : Google account email for testing\n   - `GOOGLE_PROJECT_ID` : Google project ID\n   - `GOOGLE_CLIENT_ID` : Google client ID\n   - `GOOGLE_CLIENT_SECRET` : Google client secret\n\n2. E2E test dependencies installed:\n\n```bash\nuv pip install -e \".[e2e]\"\n```\n\n#### Test Execution Commands\n\n- Run all E2E tests:\n\n```bash\ndotenvx run -f .env.local -- uv run make mcp-all-e2e-tests\n```\n\n- Run tests for individual services:\n\n```bash\n# Gmail tests\ndotenvx run -f .env.local -- uv run make mcp-e2e-tests\n\n# Google Calendar tests\ndotenvx run -f .env.local -- uv run make mcp-google-e2e-tests\n\n# Google Drive tests\ndotenvx run -f .env.local -- uv run make mcp-gdrive-e2e-tests\n\n# Google Tasks tests\ndotenvx run -f .env.local -- uv run make mcp-tasks-e2e-tests\n\n# Google Contacts tests\ndotenvx run -f .env.local -- uv run make mcp-contacts-e2e-tests\n```\n\n#### Important Notes\n\n- E2E tests access real Google accounts, so be careful not to affect production environments\n- E2E tests are automatically skipped in CI environments\n- Temporary authentication files are created during test execution but are automatically deleted afterward\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftumf%2Ffastmcp-gsuite","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ftumf%2Ffastmcp-gsuite","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftumf%2Ffastmcp-gsuite/lists"}