# mcp-personal

MCP server exposing Gmail, Outlook and Mercadona tools for Cursor and LangChain.

## Installation

```bash
npm install
```

Copy environment variables and fill in your credentials:

```bash
cp .env.example .env
# Edit .env with your Google and/or Microsoft app credentials
```

## Credentials

### Gmail

1. Go to [Google Cloud Console](https://console.cloud.google.com/).
2. Create or select a project, then enable the **Gmail API**.
3. Under **APIs & Services → Credentials**, create an **OAuth 2.0 Client ID** (Desktop app or Web application; if Web, set redirect URI to `http://localhost:3333/oauth2callback` or the value you use for `GOOGLE_REDIRECT_URI` so it does not clash with the MCP server port).
4. Put the Client ID and Client Secret in `.env` as `GOOGLE_CLIENT_ID` and `GOOGLE_CLIENT_SECRET`.

### Outlook

1. Go to [Azure Portal](https://portal.azure.com/) → **App registrations** → **New registration**.
2. Set supported account types and redirect URI as needed. For device code flow, no redirect is required.
3. Under **Certificates & secrets**, create a client secret if your app type needs it (e.g. confidential client).
4. Under **API permissions**, add Microsoft Graph → Delegated: `Mail.Read`, `Mail.Send`, `User.Read`, `offline_access`.
5. Put Application (client) ID and Directory (tenant) ID in `.env` as `AZURE_CLIENT_ID` and `AZURE_TENANT_ID`. Add `AZURE_CLIENT_SECRET` if applicable.

## Auth scripts (generate token files)

Run once (or when tokens expire) to write `gmail-tokens.json` and/or `outlook-tokens.json` in the project root. These files are gitignored.

```bash
npm run gmail:auth
npm run outlook:auth
```

## Run the server

```bash
# Development
npm run dev

# Production (build first)
npm run build
npm start
```

Server listens on `http://0.0.0.0:3000` by default (override with `PORT` in `.env`). MCP endpoint: **POST** `http://localhost:3000/mcp`.

## Configure MCP in Cursor

1. Open Cursor **Settings** → **MCP** (or edit your MCP config file).
2. Add a **Streamable HTTP** (or HTTP) MCP server with:
   - **URL**: `http://localhost:3000/mcp` (or your deployed URL).
   - **Headers** (if you set `MCP_API_KEY` in `.env`):  
     `Authorization: Bearer <your MCP_API_KEY value>`

Example config (structure may vary by Cursor version):

```json
{
  "mcpServers": {
    "mcp-personal": {
      "url": "http://localhost:3000/mcp",
      "headers": {
        "Authorization": "Bearer YOUR_MCP_API_KEY"
      }
    }
  }
}
```

If you do not set `MCP_API_KEY`, omit the `Authorization` header.

## Tools

| Tool | Description |
|------|-------------|
| `echo` | Echo back a message (test tool). |
| `gmail_list` | List Gmail messages (maxResults, optional labelIds). |
| `gmail_get` | Get a single Gmail message by ID. |
| `gmail_send` | Send an email via Gmail (to, subject, body). |
| `outlook_list` | List Outlook messages (maxResults, optional folder). |
| `outlook_get` | Get a single Outlook message by ID. |
| `outlook_send` | Send an email via Outlook (to, subject, body). |
| `mercadona_search` | Search Mercadona products (query). Returns name, price, link. Experimental; site may change. |

## Environment variables (reference)

| Variable | Description |
|----------|-------------|
| `PORT` | Server port (default 3000). |
| `MCP_API_KEY` | Optional API key; if set, clients must send `Authorization: Bearer <key>`. |
| `GOOGLE_CLIENT_ID` | Gmail OAuth client ID. |
| `GOOGLE_CLIENT_SECRET` | Gmail OAuth client secret. |
| `GOOGLE_REDIRECT_URI` | OAuth redirect URI (e.g. `http://localhost:3333/oauth2callback`). |
| `AZURE_CLIENT_ID` | Azure app (client) ID. |
| `AZURE_TENANT_ID` | Azure tenant ID (often `common`). |
| `AZURE_CLIENT_SECRET` | Azure client secret if required by app type. |
| `GMAIL_TOKENS_PATH` | Optional path to Gmail tokens file (default: project root `gmail-tokens.json`). |
| `OUTLOOK_TOKENS_PATH` | Optional path to Outlook tokens file (default: project root `outlook-tokens.json`). |

Token files `gmail-tokens.json` and `outlook-tokens.json` are created by the auth scripts and must not be committed.

**Mercadona:** The `mercadona_search` tool uses Playwright. On first use you may need to install browsers: `npx playwright install chromium`.