{"_id":"@aot-tech/gmail-mcp-server","_rev":"4-966aab46a2951529c9ac82c8049e4f3b","name":"@aot-tech/gmail-mcp-server","dist-tags":{"latest":"1.0.3"},"versions":{"1.0.1":{"name":"@aot-tech/gmail-mcp-server","version":"1.0.1","keywords":["mcp","gmail","email","model-context-protocol","bearer-token","google","api","mail"],"author":{"name":"AOT Team"},"license":"MIT","_id":"@aot-tech/gmail-mcp-server@1.0.1","maintainers":[{"name":"gopu-aot","email":"gopu.k@aot-technologies.com"},{"name":"syama.sundara","email":"syama.sundara@aot-technologies.com"},{"name":"hasgar-aot","email":"hasgar.d@aot-technologies.com"}],"bin":{"gmail-mcp-server":"build/index.js"},"dist":{"shasum":"df06785b501e4cf545b810cd296f17d9e2e9e149","tarball":"https://registry.npmjs.org/@aot-tech/gmail-mcp-server/-/gmail-mcp-server-1.0.1.tgz","fileCount":41,"integrity":"sha512-F3KBDG2HV0FmYP3okVakiyE1Hjtl0BZk4nDYjkYd3ctoP55D6wZaRj697z+7+n335N1gF5spWVpGL3GqdtJmhw==","signatures":[{"sig":"MEUCIHKhMAUgt1CqhGGdAbJ5T1ARqk9CqrXYFC0nxWVxUspmAiEA8ixKuGCZkQAVOdkc0O70/nMieUpTaJU98dDaEhEMo9k=","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":72889},"main":"build/index.js","type":"module","types":"./build/index.d.ts","engines":{"node":">=18"},"gitHead":"4be4c76365e62a22e396db5dbf9958c720545b31","scripts":{"dev":"tsx src/index.ts","build":"tsc","start":"node build/index.js","prepublishOnly":"npm run build"},"_npmUser":{"name":"syama.sundara","actor":{"name":"syama.sundara","type":"user","email":"syama.sundara@aot-technologies.com"},"email":"syama.sundara@aot-technologies.com"},"_npmVersion":"10.8.2","description":"Gmail MCP Server with Bearer Token Authentication - A Model Context Protocol server for Gmail access","directories":{},"_nodeVersion":"20.18.3","dependencies":{"zod":"^3.22.4","@modelcontextprotocol/sdk":"^0.6.0"},"_hasShrinkwrap":false,"devDependencies":{"tsx":"^4.7.0","typescript":"^5.3.0","@types/node":"^20.10.0"},"_npmOperationalInternal":{"tmp":"tmp/gmail-mcp-server_1.0.1_1752056011643_0.7503286010279049","host":"s3://npm-registry-packages-npm-production"}},"1.0.2":{"name":"@aot-tech/gmail-mcp-server","version":"1.0.2","keywords":["mcp","gmail","email","model-context-protocol","bearer-token","google","api","mail"],"author":{"name":"AOT Team"},"license":"MIT","_id":"@aot-tech/gmail-mcp-server@1.0.2","maintainers":[{"name":"gopu-aot","email":"gopu.k@aot-technologies.com"},{"name":"syama.sundara","email":"syama.sundara@aot-technologies.com"},{"name":"hasgar-aot","email":"hasgar.d@aot-technologies.com"}],"bin":{"gmail-mcp-server":"build/index.js"},"dist":{"shasum":"c72a90aff6892f7ef63c1073ffe0d494c9c1b260","tarball":"https://registry.npmjs.org/@aot-tech/gmail-mcp-server/-/gmail-mcp-server-1.0.2.tgz","fileCount":28,"integrity":"sha512-F9Acwqu5aMewMrDk9tHBtXW/Et1skud6eH+4frsctdk11fMLB8nNBE4+JKb43LFXeHElqE5osvTNcaKrczQ2lg==","signatures":[{"sig":"MEYCIQC2YMajtU6zvmY2fXMZfK+erAiodafzfaXa/5cHuE+h1AIhAN3NCukK5rKYm1UTGmqw/TSvmYVkU+de6LQ3rbRgJ9Er","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":50363},"main":"build/index.js","types":"./build/index.d.ts","engines":{"node":">=20.0.0"},"gitHead":"0d15cf04883f32c048d7beb91bf35a32e0fa748d","scripts":{"build":"tsc","start":"node build/index.js","prepublishOnly":"npm run build"},"_npmUser":{"name":"syama.sundara","actor":{"name":"syama.sundara","type":"user","email":"syama.sundara@aot-technologies.com"},"email":"syama.sundara@aot-technologies.com"},"_npmVersion":"11.4.2","description":"Gmail MCP Server with Bearer Token Authentication - A Model Context Protocol server for Gmail access","directories":{},"_nodeVersion":"20.18.3","dependencies":{"zod":"^3.22.4","ts-node":"^10.9.2","tsconfig-paths":"^4.2.0","@modelcontextprotocol/sdk":"^1.15.0"},"_hasShrinkwrap":false,"devDependencies":{"tsx":"^4.7.0","typescript":"^5.3.0","@types/node":"^20.10.0"},"_npmOperationalInternal":{"tmp":"tmp/gmail-mcp-server_1.0.2_1752070597347_0.833207880508773","host":"s3://npm-registry-packages-npm-production"}},"1.0.3":{"name":"@aot-tech/gmail-mcp-server","version":"1.0.3","keywords":["mcp","gmail","email","model-context-protocol","bearer-token","google","api","mail"],"author":{"name":"AOT Team"},"license":"MIT","_id":"@aot-tech/gmail-mcp-server@1.0.3","maintainers":[{"name":"gopu-aot","email":"gopu.k@aot-technologies.com"},{"name":"syama.sundara","email":"syama.sundara@aot-technologies.com"},{"name":"hasgar-aot","email":"hasgar.d@aot-technologies.com"}],"bin":{"gmail-mcp-server":"build/index.js"},"dist":{"shasum":"cb9a1302dbbf6023559a75119bc9d369f7e12a25","tarball":"https://registry.npmjs.org/@aot-tech/gmail-mcp-server/-/gmail-mcp-server-1.0.3.tgz","fileCount":28,"integrity":"sha512-bJ8Pd4E1ye43nKK6swIoQJI1ftPWPs5diLc8XiusiJoV9u7tq8soZl1upLv9E2GoKxyBU10m3LQPULWRYai/lg==","signatures":[{"sig":"MEYCIQDo8JZ+KROFh1gxQbtgpQ2EC5hsFKiCSwb9kHJF2h5zJQIhAJtIUyWKna3jZZv0o5IdQMGs/P/RL2D4vsrIpY8VzwHo","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":53415},"main":"build/index.js","types":"./build/index.d.ts","engines":{"node":">=20.0.0"},"gitHead":"9e383ce7a907c984d2ea8f0f3c98a1adccd090f5","scripts":{"build":"tsc","start":"node build/index.js","prepublishOnly":"npm run build"},"_npmUser":{"name":"syama.sundara","email":"syama.sundara@aot-technologies.com"},"_npmVersion":"11.4.2","description":"Gmail MCP Server with Bearer Token Authentication - A Model Context Protocol server for Gmail access","directories":{},"_nodeVersion":"20.18.3","dependencies":{"zod":"^3.22.4","ts-node":"^10.9.2","tsconfig-paths":"^4.2.0","@modelcontextprotocol/sdk":"^1.15.0"},"_hasShrinkwrap":false,"devDependencies":{"tsx":"^4.7.0","typescript":"^5.3.0","@types/node":"^20.10.0"},"_npmOperationalInternal":{"tmp":"tmp/gmail-mcp-server_1.0.3_1752768357034_0.23262175104921523","host":"s3://npm-registry-packages-npm-production"}}},"time":{"created":"2025-07-09T10:13:31.584Z","modified":"2026-03-23T06:53:03.925Z","1.0.1":"2025-07-09T10:13:31.836Z","1.0.2":"2025-07-09T14:16:37.527Z","1.0.3":"2025-07-17T16:05:57.250Z"},"author":{"name":"AOT Team"},"license":"MIT","keywords":["mcp","gmail","email","model-context-protocol","bearer-token","google","api","mail"],"description":"Gmail MCP Server with Bearer Token Authentication - A Model Context Protocol server for Gmail access","maintainers":[{"email":"syama.sundara@aot-technologies.com","name":"syama.sundara"},{"email":"hasgar.d@aot-technologies.com","name":"hasgar-aot"}],"readme":"# JIRA MCP Server\r\n\r\nA Model Context Protocol (MCP) server implementation that provides access to JIRA data with relationship tracking, optimized data payloads, and data cleaning for AI context windows.\r\n\r\nℹ️ There is a separate MCP server [for Confluence](https://github.com/cosmix/confluence-mcp)\r\n\r\n---\r\n\r\n## Jira Cloud & Jira Server (Data Center) Support\r\n\r\nThis MCP server supports both **Jira Cloud** and **Jira Server (Data Center)** instances. You can select which type to use by setting the `JIRA_TYPE` environment variable:\r\n\r\n- `cloud` (default): For Jira Cloud (Atlassian-hosted)\r\n- `server`: For Jira Server/Data Center (self-hosted)\r\n\r\nThe server will automatically use the correct API version and authentication method for the selected type.\r\n\r\n---\r\n\r\n## Features\r\n\r\n- Search JIRA issues using JQL (maximum 50 results per request)\r\n- Retrieve epic children with comment history and optimized payloads (maximum 100 issues per request)\r\n- Get detailed issue information including comments and related issues\r\n- Create, update, and manage JIRA issues\r\n- Add comments to issues\r\n- Extract issue mentions from Atlassian Document Format\r\n- Track issue relationships (mentions, links, parent/child, epics)\r\n- Clean and transform rich JIRA content for AI context efficiency\r\n- Support for file attachments with secure multipart upload handling\r\n- **Supports both Jira Cloud and Jira Server (Data Center) APIs**\r\n\r\n## Prerequisites\r\n\r\n- [Bun](https://bun.sh) (v1.0.0 or higher)\r\n- JIRA account with API access\r\n\r\n## Environment Variables\r\n\r\n```bash\r\nJIRA_API_TOKEN=your_api_token\r\nJIRA_BASE_URL=your_jira_instance_url  # e.g., https://your-domain.atlassian.net\r\nJIRA_USER_EMAIL=your_email\r\nJIRA_TYPE=cloud   # or 'server' for Jira Server/Data Center (optional, defaults to 'cloud')\r\n```\r\n\r\n## Installation & Setup\r\n\r\n### 1. Clone the repository:\r\n\r\n```bash\r\ngit clone [repository-url]\r\ncd jira-mcp\r\n```\r\n\r\n### 2. Install dependencies and build:\r\n\r\n```bash\r\nbun install\r\nbun run build\r\n```\r\n\r\n### 3. Configure the MCP server:\r\n\r\nEdit the appropriate configuration file:\r\n\r\n**macOS:**\r\n\r\n- Cline: `~/Library/Application Support/Code/User/globalStorage/saoudrizwan.claude-dev/settings/cline_mcp_settings.json`\r\n- Claude Desktop: `~/Library/Application Support/Claude/claude_desktop_config.json`\r\n\r\n**Windows:**\r\n\r\n- Cline: `%APPDATA%\\Code\\User\\globalStorage\\saoudrizwan.claude-dev\\settings\\cline_mcp_settings.json`\r\n- Claude Desktop: `%APPDATA%\\Claude Desktop\\claude_desktop_config.json`\r\n\r\n**Linux:**\r\n\r\n- Cline: `~/.config/Code/User/globalStorage/saoudrizwan.claude-dev/settings/cline_mcp_settings.json`\r\n- Claude Desktop: _sadly doesn't exist yet_\r\n\r\nAdd the following configuration under the `mcpServers` object:\r\n\r\n```json\r\n{\r\n  \"mcpServers\": {\r\n    \"jira\": {\r\n      \"command\": \"node\",\r\n      \"args\": [\"/absolute/path/to/jira-mcp/build/index.js\"],\r\n      \"env\": {\r\n        \"JIRA_API_TOKEN\": \"your_api_token\",\r\n        \"JIRA_BASE_URL\": \"your_jira_instance_url\",\r\n        \"JIRA_USER_EMAIL\": \"your_email\",\r\n        \"JIRA_TYPE\": \"cloud\"\r\n      }\r\n    }\r\n  }\r\n}\r\n```\r\n\r\n### 4. Restart the MCP server.\r\n\r\nWithin Cline's MCP settings, restart the MCP server. Restart Claude Desktop to load the new MCP server.\r\n\r\n## Development\r\n\r\nRun tests:\r\n\r\n```bash\r\nbun test\r\n```\r\n\r\nWatch mode for development:\r\n\r\n```bash\r\nbun run dev\r\n```\r\n\r\nTo rebuild after changes:\r\n\r\n```bash\r\nbun run build\r\n```\r\n\r\n## Project Structure (Updated)\r\n\r\nThe server has been restructured to follow best practices with organized tool modules:\r\n\r\n```\r\nsrc/\r\n├── index.ts              # Main server entry point\r\n├── config.ts             # Configuration management  \r\n├── types/\r\n│   └── index.ts          # TypeScript type definitions\r\n├── utils/\r\n│   └── auth.ts           # Authentication utilities\r\n├── tools/                # MCP tools organized by category\r\n│   ├── issues.ts         # Issue management tools\r\n│   ├── projects.ts       # Project management tools\r\n│   ├── users.ts          # User management tools\r\n│   ├── metadata.ts       # Metadata tools (types, priorities, statuses)\r\n│   ├── boards.ts         # Agile/board management tools\r\n│   └── resources.ts      # Resource management tools\r\n├── services/\r\n│   ├── jira-api.ts       # JIRA Cloud API service\r\n│   └── jira-server-api.ts # JIRA Server API service\r\n└── validation/           # Zod validation schemas\r\n    ├── issues/\r\n    ├── projects/\r\n    └── users/\r\n```\r\n\r\n## Available MCP Tools\r\n\r\n### search_issues\r\n\r\nSearch JIRA issues using JQL. Returns up to 50 results per request.\r\n\r\nInput Schema:\r\n\r\n```typescript\r\n{\r\n  searchString: string; // JQL search string\r\n}\r\n```\r\n\r\n### get_epic_children\r\n\r\nGet all child issues in an epic including their comments and relationship data. Limited to 100 issues per request.\r\n\r\nInput Schema:\r\n\r\n```typescript\r\n{\r\n  epicKey: string; // The key of the epic issue\r\n}\r\n```\r\n\r\n### get_issue\r\n\r\nGet detailed information about a specific JIRA issue including comments and all relationships.\r\n\r\nInput Schema:\r\n\r\n```typescript\r\n{\r\n  issueId: string; // The ID or key of the JIRA issue\r\n}\r\n```\r\n\r\n### create_issue\r\n\r\nCreate a new JIRA issue with specified fields.\r\n\r\nInput Schema:\r\n\r\n```typescript\r\n{\r\n  projectKey: string, // The project key where the issue will be created\r\n  issueType: string, // The type of issue (e.g., \"Bug\", \"Story\", \"Task\")\r\n  summary: string, // The issue summary/title\r\n  description?: string, // Optional issue description\r\n  fields?: { // Optional additional fields\r\n    [key: string]: any\r\n  }\r\n}\r\n```\r\n\r\n### update_issue\r\n\r\nUpdate fields of an existing JIRA issue.\r\n\r\nInput Schema:\r\n\r\n```typescript\r\n{\r\n  issueKey: string, // The key of the issue to update\r\n  fields: { // Fields to update\r\n    [key: string]: any\r\n  }\r\n}\r\n```\r\n\r\n### add_attachment\r\n\r\nAdd a file attachment to a JIRA issue.\r\n\r\nInput Schema:\r\n\r\n```typescript\r\n{\r\n  issueKey: string, // The key of the issue\r\n  fileContent: string, // Base64 encoded file content\r\n  filename: string // Name of the file to be attached\r\n}\r\n```\r\n\r\n### add_comment\r\n\r\nAdd a comment to a JIRA issue. Accepts plain text and converts it to the required Atlassian Document Format internally.\r\n\r\nInput Schema:\r\n\r\n```typescript\r\n{\r\n  issueIdOrKey: string, // The ID or key of the issue to add the comment to\r\n  body: string // The content of the comment (plain text)\r\n}\r\n```\r\n\r\n## Data Cleaning Features\r\n\r\n- Extracts text from Atlassian Document Format\r\n- Tracks issue mentions in descriptions and comments\r\n- Maintains formal issue links with relationship types\r\n- Preserves parent/child relationships\r\n- Tracks epic associations\r\n- Includes comment history with author information\r\n- Removes unnecessary metadata from responses\r\n- Recursively processes content nodes for mentions\r\n- Deduplicates issue mentions\r\n\r\n## Technical Details\r\n\r\n- Built with TypeScript in strict mode\r\n- Uses Bun runtime for improved performance\r\n- Vite for optimized builds\r\n- Uses JIRA REST API v3\r\n- Basic authentication with API tokens\r\n- Batched API requests for related data\r\n- Optimized response payloads for AI context windows\r\n- Efficient transformation of complex Atlassian structures\r\n- Robust error handling\r\n- Rate limiting considerations\r\n- Maximum limits:\r\n  - Search results: 50 issues per request\r\n  - Epic children: 100 issues per request\r\n- Support for multipart form data for secure file attachments\r\n- Automatic content type detection and validation\r\n\r\n## Error Handling\r\n\r\nThe server implements a comprehensive error handling strategy:\r\n\r\n- Network error detection and appropriate messaging\r\n- HTTP status code handling (especially 404 for issues)\r\n- Detailed error messages with status codes\r\n- Error details logging to console\r\n- Input validation for all parameters\r\n- Safe error propagation through MCP protocol\r\n- Specialized handling for common JIRA API errors\r\n- Base64 validation for attachments\r\n- Multipart request failure handling\r\n- Rate limit detection\r\n- Attachment parameter validation\r\n\r\n## LICENCE\r\n\r\nThis project is licensed under the MIT License - see the [LICENCE](LICENCE) file for details.\r\n\r\n# Gmail MCP Server\r\n\r\nA Model Context Protocol (MCP) server implementation that provides access to Gmail functionality using Bearer token authentication.\r\n\r\n## Features\r\n\r\n- **Send emails** - Send emails via Gmail with support for TO, CC, BCC recipients\r\n- **Search emails** - Search emails using Gmail's powerful search syntax\r\n- **Read emails** - Retrieve and read email content by message ID\r\n- **Delete emails** - Delete emails by message ID\r\n- **List labels** - Get all available Gmail labels\r\n- **Bearer token authentication** - Secure authentication using Gmail app passwords\r\n\r\n## Prerequisites\r\n\r\n- Node.js (v18 or higher)\r\n- Gmail account with app password enabled\r\n- MCP client (Claude Desktop, Cline, etc.)\r\n\r\n## Authentication Setup\r\n\r\nThis server uses Gmail app passwords for authentication. Here's how to set it up:\r\n\r\n1. Go to your Google Account settings (myaccount.google.com)\r\n2. Enable 2-factor authentication if not already enabled\r\n3. Go to Security > App passwords\r\n4. Generate a new app password for 'Mail'\r\n5. Configure your MCP client to send Bearer token as: `your_email@gmail.com:your_16_character_app_password`\r\n\r\n## Installation\r\n\r\n### From npm\r\n\r\n```bash\r\nnpm install -g gmail-bearer-mcp-server\r\n```\r\n\r\n### From source\r\n\r\n```bash\r\ngit clone [repository-url]\r\ncd email\r\nnpm install\r\nnpm run build\r\n```\r\n\r\n## Configuration\r\n\r\n### For MCP Clients\r\n\r\nEdit your MCP client configuration file:\r\n\r\n**macOS:**\r\n- Cline: `~/Library/Application Support/Code/User/globalStorage/saoudrizwan.claude-dev/settings/cline_mcp_settings.json`\r\n- Claude Desktop: `~/Library/Application Support/Claude/claude_desktop_config.json`\r\n\r\n**Windows:**\r\n- Cline: `%APPDATA%\\Code\\User\\globalStorage\\saoudrizwan.claude-dev\\settings\\cline_mcp_settings.json`\r\n- Claude Desktop: `%APPDATA%\\Claude Desktop\\claude_desktop_config.json`\r\n\r\n**Linux:**\r\n- Cline: `~/.config/Code/User/globalStorage/saoudrizwan.claude-dev/settings/cline_mcp_settings.json`\r\n\r\nAdd the following configuration:\r\n\r\n```json\r\n{\r\n  \"mcpServers\": {\r\n    \"gmail\": {\r\n      \"command\": \"gmail-bearer-mcp\",\r\n      \"env\": {\r\n        \"GMAIL_BEARER_TOKEN\": \"your_email@gmail.com:your_app_password\"\r\n      }\r\n    }\r\n  }\r\n}\r\n```\r\n\r\nAlternatively, you can provide the bearer token via headers:\r\n- `Authorization: Bearer your_email@gmail.com:your_app_password`\r\n- `X-Gmail-Token: your_email@gmail.com:your_app_password`\r\n\r\n## Available Tools\r\n\r\n### send_email\r\n\r\nSend an email via Gmail.\r\n\r\n**Parameters:**\r\n- `to` (required): Array of recipient email addresses\r\n- `subject` (required): Email subject line\r\n- `body` (required): Email body content (plain text)\r\n- `cc` (optional): Array of CC email addresses\r\n- `bcc` (optional): Array of BCC email addresses\r\n\r\n**Example:**\r\n```json\r\n{\r\n  \"to\": [\"recipient@example.com\"],\r\n  \"subject\": \"Test Email\",\r\n  \"body\": \"This is a test email from the Gmail MCP server.\",\r\n  \"cc\": [\"cc@example.com\"],\r\n  \"bcc\": [\"bcc@example.com\"]\r\n}\r\n```\r\n\r\n### search_emails\r\n\r\nSearch emails using Gmail's search syntax.\r\n\r\n**Parameters:**\r\n- `query` (required): Gmail search query\r\n- `maxResults` (optional): Maximum number of results (1-500, default: 10)\r\n\r\n**Example queries:**\r\n- `from:example@gmail.com` - Emails from specific sender\r\n- `has:attachment` - Emails with attachments\r\n- `after:2024/01/01` - Emails after specific date\r\n- `subject:important` - Emails with \"important\" in subject\r\n\r\n### read_email\r\n\r\nRead the content of a specific email.\r\n\r\n**Parameters:**\r\n- `messageId` (required): Gmail message ID\r\n\r\n### delete_email\r\n\r\nDelete an email by message ID.\r\n\r\n**Parameters:**\r\n- `messageId` (required): Gmail message ID to delete\r\n\r\n### list_labels\r\n\r\nList all available Gmail labels.\r\n\r\n**Parameters:** None\r\n\r\n## Development\r\n\r\n### Build\r\n\r\n```bash\r\nnpm run build\r\n```\r\n\r\n### Development mode\r\n\r\n```bash\r\nnpm run dev\r\n```\r\n\r\n### Start\r\n\r\n```bash\r\nnpm start\r\n```\r\n\r\n## Security\r\n\r\n- This server uses Gmail app passwords for authentication\r\n- Bearer tokens are extracted from request headers\r\n- No credentials are stored in the server\r\n- All communication uses HTTPS via Gmail's API\r\n\r\n## Troubleshooting\r\n\r\n### Authentication Issues\r\n\r\n1. **\"No bearer token available\"** - Make sure you're providing the bearer token in one of these ways:\r\n   - `Authorization: Bearer your_email:your_app_password` header\r\n   - `X-Gmail-Token: your_email:your_app_password` header\r\n   - `GMAIL_BEARER_TOKEN=your_email:your_app_password` environment variable\r\n\r\n2. **\"Gmail API request failed: 401\"** - Your app password may be incorrect or expired. Generate a new one.\r\n\r\n3. **\"Gmail API request failed: 403\"** - Your Gmail account may have restrictions. Check your Google Account security settings.\r\n\r\n### Common Issues\r\n\r\n- Make sure 2-factor authentication is enabled on your Google account\r\n- App passwords only work with 2FA enabled\r\n- Use the full email address followed by colon and the 16-character app password\r\n- Remove any spaces from the app password\r\n\r\n## License\r\n\r\nMIT\r\n","readmeFilename":"README.md"}