@aot-tech/gmail-mcp-server/README.md

Gmail MCP Server with Bearer Token Authentication - A Model Context Protocol server for Gmail access

# JIRA MCP Server

A 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.

ℹ️ There is a separate MCP server [for Confluence](https://github.com/cosmix/confluence-mcp)

---

## Jira Cloud & Jira Server (Data Center) Support

This 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:

- `cloud` (default): For Jira Cloud (Atlassian-hosted)
- `server`: For Jira Server/Data Center (self-hosted)

The server will automatically use the correct API version and authentication method for the selected type.

---

## Features

- Search JIRA issues using JQL (maximum 50 results per request)
- Retrieve epic children with comment history and optimized payloads (maximum 100 issues per request)
- Get detailed issue information including comments and related issues
- Create, update, and manage JIRA issues
- Add comments to issues
- Extract issue mentions from Atlassian Document Format
- Track issue relationships (mentions, links, parent/child, epics)
- Clean and transform rich JIRA content for AI context efficiency
- Support for file attachments with secure multipart upload handling
- **Supports both Jira Cloud and Jira Server (Data Center) APIs**

## Prerequisites

- [Bun](https://bun.sh) (v1.0.0 or higher)
- JIRA account with API access

## Environment Variables

```bash
JIRA_API_TOKEN=your_api_token
JIRA_BASE_URL=your_jira_instance_url  # e.g., https://your-domain.atlassian.net
JIRA_USER_EMAIL=your_email
JIRA_TYPE=cloud   # or 'server' for Jira Server/Data Center (optional, defaults to 'cloud')
```

## Installation & Setup

### 1. Clone the repository:

```bash
git clone [repository-url]
cd jira-mcp
```

### 2. Install dependencies and build:

```bash
bun install
bun run build
```

### 3. Configure the MCP server:

Edit the appropriate configuration file:

**macOS:**

- Cline: `~/Library/Application Support/Code/User/globalStorage/saoudrizwan.claude-dev/settings/cline_mcp_settings.json`
- Claude Desktop: `~/Library/Application Support/Claude/claude_desktop_config.json`

**Windows:**

- Cline: `%APPDATA%\Code\User\globalStorage\saoudrizwan.claude-dev\settings\cline_mcp_settings.json`
- Claude Desktop: `%APPDATA%\Claude Desktop\claude_desktop_config.json`

**Linux:**

- Cline: `~/.config/Code/User/globalStorage/saoudrizwan.claude-dev/settings/cline_mcp_settings.json`
- Claude Desktop: _sadly doesn't exist yet_

Add the following configuration under the `mcpServers` object:

```json
{
  "mcpServers": {
    "jira": {
      "command": "node",
      "args": ["/absolute/path/to/jira-mcp/build/index.js"],
      "env": {
        "JIRA_API_TOKEN": "your_api_token",
        "JIRA_BASE_URL": "your_jira_instance_url",
        "JIRA_USER_EMAIL": "your_email",
        "JIRA_TYPE": "cloud"
      }
    }
  }
}
```

### 4. Restart the MCP server.

Within Cline's MCP settings, restart the MCP server. Restart Claude Desktop to load the new MCP server.

## Development

Run tests:

```bash
bun test
```

Watch mode for development:

```bash
bun run dev
```

To rebuild after changes:

```bash
bun run build
```

## Project Structure (Updated)

The server has been restructured to follow best practices with organized tool modules:

```
src/
├── index.ts              # Main server entry point
├── config.ts             # Configuration management  
├── types/
│   └── index.ts          # TypeScript type definitions
├── utils/
│   └── auth.ts           # Authentication utilities
├── tools/                # MCP tools organized by category
│   ├── issues.ts         # Issue management tools
│   ├── projects.ts       # Project management tools
│   ├── users.ts          # User management tools
│   ├── metadata.ts       # Metadata tools (types, priorities, statuses)
│   ├── boards.ts         # Agile/board management tools
│   └── resources.ts      # Resource management tools
├── services/
│   ├── jira-api.ts       # JIRA Cloud API service
│   └── jira-server-api.ts # JIRA Server API service
└── validation/           # Zod validation schemas
    ├── issues/
    ├── projects/
    └── users/
```

## Available MCP Tools

### search_issues

Search JIRA issues using JQL. Returns up to 50 results per request.

Input Schema:

```typescript
{
  searchString: string; // JQL search string
}
```

### get_epic_children

Get all child issues in an epic including their comments and relationship data. Limited to 100 issues per request.

Input Schema:

```typescript
{
  epicKey: string; // The key of the epic issue
}
```

### get_issue

Get detailed information about a specific JIRA issue including comments and all relationships.

Input Schema:

```typescript
{
  issueId: string; // The ID or key of the JIRA issue
}
```

### create_issue

Create a new JIRA issue with specified fields.

Input Schema:

```typescript
{
  projectKey: string, // The project key where the issue will be created
  issueType: string, // The type of issue (e.g., "Bug", "Story", "Task")
  summary: string, // The issue summary/title
  description?: string, // Optional issue description
  fields?: { // Optional additional fields
    [key: string]: any
  }
}
```

### update_issue

Update fields of an existing JIRA issue.

Input Schema:

```typescript
{
  issueKey: string, // The key of the issue to update
  fields: { // Fields to update
    [key: string]: any
  }
}
```

### add_attachment

Add a file attachment to a JIRA issue.

Input Schema:

```typescript
{
  issueKey: string, // The key of the issue
  fileContent: string, // Base64 encoded file content
  filename: string // Name of the file to be attached
}
```

### add_comment

Add a comment to a JIRA issue. Accepts plain text and converts it to the required Atlassian Document Format internally.

Input Schema:

```typescript
{
  issueIdOrKey: string, // The ID or key of the issue to add the comment to
  body: string // The content of the comment (plain text)
}
```

## Data Cleaning Features

- Extracts text from Atlassian Document Format
- Tracks issue mentions in descriptions and comments
- Maintains formal issue links with relationship types
- Preserves parent/child relationships
- Tracks epic associations
- Includes comment history with author information
- Removes unnecessary metadata from responses
- Recursively processes content nodes for mentions
- Deduplicates issue mentions

## Technical Details

- Built with TypeScript in strict mode
- Uses Bun runtime for improved performance
- Vite for optimized builds
- Uses JIRA REST API v3
- Basic authentication with API tokens
- Batched API requests for related data
- Optimized response payloads for AI context windows
- Efficient transformation of complex Atlassian structures
- Robust error handling
- Rate limiting considerations
- Maximum limits:
  - Search results: 50 issues per request
  - Epic children: 100 issues per request
- Support for multipart form data for secure file attachments
- Automatic content type detection and validation

## Error Handling

The server implements a comprehensive error handling strategy:

- Network error detection and appropriate messaging
- HTTP status code handling (especially 404 for issues)
- Detailed error messages with status codes
- Error details logging to console
- Input validation for all parameters
- Safe error propagation through MCP protocol
- Specialized handling for common JIRA API errors
- Base64 validation for attachments
- Multipart request failure handling
- Rate limit detection
- Attachment parameter validation

## LICENCE

This project is licensed under the MIT License - see the [LICENCE](LICENCE) file for details.

# Gmail MCP Server

A Model Context Protocol (MCP) server implementation that provides access to Gmail functionality using Bearer token authentication.

## Features

- **Send emails** - Send emails via Gmail with support for TO, CC, BCC recipients
- **Search emails** - Search emails using Gmail's powerful search syntax
- **Read emails** - Retrieve and read email content by message ID
- **Delete emails** - Delete emails by message ID
- **List labels** - Get all available Gmail labels
- **Bearer token authentication** - Secure authentication using Gmail app passwords

## Prerequisites

- Node.js (v18 or higher)
- Gmail account with app password enabled
- MCP client (Claude Desktop, Cline, etc.)

## Authentication Setup

This server uses Gmail app passwords for authentication. Here's how to set it up:

1. Go to your Google Account settings (myaccount.google.com)
2. Enable 2-factor authentication if not already enabled
3. Go to Security > App passwords
4. Generate a new app password for 'Mail'
5. Configure your MCP client to send Bearer token as: `your_email@gmail.com:your_16_character_app_password`

## Installation

### From npm

```bash
npm install -g gmail-bearer-mcp-server
```

### From source

```bash
git clone [repository-url]
cd email
npm install
npm run build
```

## Configuration

### For MCP Clients

Edit your MCP client configuration file:

**macOS:**
- Cline: `~/Library/Application Support/Code/User/globalStorage/saoudrizwan.claude-dev/settings/cline_mcp_settings.json`
- Claude Desktop: `~/Library/Application Support/Claude/claude_desktop_config.json`

**Windows:**
- Cline: `%APPDATA%\Code\User\globalStorage\saoudrizwan.claude-dev\settings\cline_mcp_settings.json`
- Claude Desktop: `%APPDATA%\Claude Desktop\claude_desktop_config.json`

**Linux:**
- Cline: `~/.config/Code/User/globalStorage/saoudrizwan.claude-dev/settings/cline_mcp_settings.json`

Add the following configuration:

```json
{
  "mcpServers": {
    "gmail": {
      "command": "gmail-bearer-mcp",
      "env": {
        "GMAIL_BEARER_TOKEN": "your_email@gmail.com:your_app_password"
      }
    }
  }
}
```

Alternatively, you can provide the bearer token via headers:
- `Authorization: Bearer your_email@gmail.com:your_app_password`
- `X-Gmail-Token: your_email@gmail.com:your_app_password`

## Available Tools

### send_email

Send an email via Gmail.

**Parameters:**
- `to` (required): Array of recipient email addresses
- `subject` (required): Email subject line
- `body` (required): Email body content (plain text)
- `cc` (optional): Array of CC email addresses
- `bcc` (optional): Array of BCC email addresses

**Example:**
```json
{
  "to": ["recipient@example.com"],
  "subject": "Test Email",
  "body": "This is a test email from the Gmail MCP server.",
  "cc": ["cc@example.com"],
  "bcc": ["bcc@example.com"]
}
```

### search_emails

Search emails using Gmail's search syntax.

**Parameters:**
- `query` (required): Gmail search query
- `maxResults` (optional): Maximum number of results (1-500, default: 10)

**Example queries:**
- `from:example@gmail.com` - Emails from specific sender
- `has:attachment` - Emails with attachments
- `after:2024/01/01` - Emails after specific date
- `subject:important` - Emails with "important" in subject

### read_email

Read the content of a specific email.

**Parameters:**
- `messageId` (required): Gmail message ID

### delete_email

Delete an email by message ID.

**Parameters:**
- `messageId` (required): Gmail message ID to delete

### list_labels

List all available Gmail labels.

**Parameters:** None

## Development

### Build

```bash
npm run build
```

### Development mode

```bash
npm run dev
```

### Start

```bash
npm start
```

## Security

- This server uses Gmail app passwords for authentication
- Bearer tokens are extracted from request headers
- No credentials are stored in the server
- All communication uses HTTPS via Gmail's API

## Troubleshooting

### Authentication Issues

1. **"No bearer token available"** - Make sure you're providing the bearer token in one of these ways:
   - `Authorization: Bearer your_email:your_app_password` header
   - `X-Gmail-Token: your_email:your_app_password` header
   - `GMAIL_BEARER_TOKEN=your_email:your_app_password` environment variable

2. **"Gmail API request failed: 401"** - Your app password may be incorrect or expired. Generate a new one.

3. **"Gmail API request failed: 403"** - Your Gmail account may have restrictions. Check your Google Account security settings.

### Common Issues

- Make sure 2-factor authentication is enabled on your Google account
- App passwords only work with 2FA enabled
- Use the full email address followed by colon and the 16-character app password
- Remove any spaces from the app password

## License

MIT