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

Go to Google Cloud Console.
Create or select a project, then enable the Gmail API.
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).
Put the Client ID and Client Secret in .env as GOOGLE_CLIENT_ID and GOOGLE_CLIENT_SECRET.

Outlook

Go to Azure Portal → App registrations → New registration.
Set supported account types and redirect URI as needed. For device code flow, no redirect is required.
Under Certificates & secrets, create a client secret if your app type needs it (e.g. confidential client).
Under API permissions, add Microsoft Graph → Delegated: Mail.Read, Mail.Send, User.Read, offline_access.
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

Open Cursor Settings → MCP (or edit your MCP config file).
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.