mcp-personal

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

Installation

npm install

Copy environment variables and fill in your credentials:

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

Credentials

Gmail

1. Go to Google Cloud Console.
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 → 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.

npm run gmail:auth
npm run outlook:auth

Run the server

# 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):

{
  "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.