MIST

MIST is an MCP server that connects AI assistants to a suite of real-world tools for note management, Gmail, Calendar, Tasks, and Git operations. It exposes structured MCP actions that allow an AI to create, read, update, and organize notes; search and manage Gmail messages; manage Google Calendar events; handle task lists and individual tasks; and perform basic Git operations within local repositories. The server handles authentication with Google APIs and routes requests to the appropriate subsystem, returning clearly defined responses that the AI can present to end users. If you’re building an assistant, you can rely on MIST to provide a consistent interface for external services rather than implementing each API integration from scratch.

To use MIST, install and run the server, then integrate it with your MCP-enabled AI assistant. The assistant can issue actions such as createNote, searchNotes, sendEmail, listCalendarEvents, createTask, commitChanges, and runGitCommand. Each action is routed through MIST’s modular managers (Note Manager, Gmail Manager, Calendar Manager, Tasks Manager, Git Manager) and ultimately to the corresponding external service APIs. Responses are returned in a structured format suitable for downstream UI or conversational prompts, enabling your AI to present results, confirm operations, or surface relevant data to users.

Prerequisites

• Python 3.13 or newer
• UV package manager (recommended) or pip
• Google account for Gmail/Calendar/Tasks integration
• Git for Git integration features

Setup steps

1. Clone the repository

   git clone https://github.com/cloaky233/mist.git cd mist

2. Install dependencies

   With UV (recommended):

   uv install

   With pip (editable install):

   pip install -e .

3. Configure environment

   Create a .env file with required configuration values. Example:

   echo "MIST_NOTES_DIR=/path/to/your/notes/directory" > .env echo "MIST_GOOGLE_CREDENTIALS_PATH=./credentials.json" >> .env echo "MIST_GOOGLE_TOKEN_PATH=./token.json" >> .env

   Edit the paths to point to your actual storage and Google credential/token files.

4. Run MIST

   uvx mist

5. Perform initial Google API setup

   • Ensure your Google Cloud project has Gmail, Calendar, and Tasks APIs enabled.
   • Follow the OAuth flow to grant access. The first run will prompt you to authorize the application and save an OAuth token to the configured path.

Environment variables and configuration

• MIST_NOTES_DIR: Directory for local note storage.
• MIST_GOOGLE_CREDENTIALS_PATH: Path to your Google API credentials JSON.
• MIST_GOOGLE_TOKEN_PATH: Path to the OAuth token file generated during setup.

Tips and common issues:

• If you encounter authentication errors with Google APIs, re-run the first-time setup to refresh credentials and ensure the credentials.json file matches your Google Cloud project.
• ForNote storage, ensure the chosen directory has read/write permissions for the user running MIST.
• If you upgrade MIST, re-check environment variable paths as some updates may introduce new configuration options.
• The API surfaces are designed to be extended; if you add new external services, consider updating or adding new manager components to MIST to keep actions consistent across AI assistants.
• For troubleshooting, inspect the logs produced by MIST to identify which manager encountered an error and what API call failed.