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.