MIST

MIST - Model Intelligence System for Tasks

MIST is a comprehensive MCP (Model Context Protocol) server that empowers AI assistants with real-world capabilities for note management, Gmail, Calendar, Tasks, and Git integration. It bridges the gap between AI assistants and external tools, enabling them to interact with your data and services through a standardized protocol.

- Manage notes: Create, edit, search, and organize notes with persistent storage
- Interact with Gmail: Search emails, read messages, send emails, manage labels
- Manage calendar events: View, create, update, and delete Google Calendar events
- Organize tasks: Create task lists, add tasks, mark tasks as complete
- Work with Git repositories: Perform Git operations like status, diff, commit, branch management

By implementing the Model Context Protocol (MCP), MIST enables AI assistants to perform actions in external systems, access real-time information, and maintain context across interactions.

- Create and store notes with rich text formatting
- Search notes by content, tags, or metadata
- Generate summaries of notes or collections
- Organize notes by subject, date, or custom categories
- Store notes locally in your filesystem

- Search emails with advanced filtering options
- Read complete email content
- Compose and send emails
- Manage email labels and organization
- Mark messages as read/unread
- Batch operations for multiple messages

- List all available calendars
- Create and manage calendar events
- Update existing events
- Search events by keyword or date range
- View detailed event information

- List and manage task lists
- Create tasks with titles, notes, and due dates
- Mark tasks as complete
- Delete completed tasks
- Organize tasks into different lists

- Perform Git operations in local repositories
- View status, diffs, and commit history
- Commit changes and manage branches
- Create, checkout and merge branches
- Manage remote repositories
- Display commit details and changes

MIST is continuously evolving to offer more integrations and features. Here's what we're planning to add:

- Google Drive Integration: Access and manage files, search documents, and analyze content
- Google Sheets Integration: Create, read, and update spreadsheets for data analysis

- Google Custom Search: Enable web search capabilities for research and information retrieval
- Knowledge Base: Build local repositories of information for offline access

- Google Classroom: Access courses, assignments, and educational materials
- Google Chat: Interact with chat spaces and messages for team collaboration

- Google Forms: Create and manage forms for data collection
- Google Maps: Add location-based services including geocoding and directions

- Enhanced Caching: Improve performance for frequently accessed data
- Multi-User Support: Add user profiles and permission management
- Expanded AI Assistant Compatibility: Support more AI assistants and models

We welcome contributions in any of these areas! Check ourContributing Guidelinesfor more information on how to get involved.

flowchart TB User[User] -->|Requests action| AI[AI Assistant] AI -->|Sends MCP request| MIST[MIST Server] subgraph "MIST Server Components" Router[MCP Request Router] NoteMgr[Note Manager] GmailMgr[Gmail Manager] TasksMgr[Tasks Manager] CalendarMgr[Calendar Manager] GitMgr[Git Manager] Auth[Authentication] end MIST --> Router Router -->|Note requests| NoteMgr Router -->|Gmail requests| GmailMgr Router -->|Tasks requests| TasksMgr Router -->|Calendar requests| CalendarMgr Router -->|Git requests| GitMgr GmailMgr -->|Auth requests| Auth TasksMgr -->|Auth requests| Auth CalendarMgr -->|Auth requests| Auth NoteMgr -->|Store/Retrieve| NoteDB[(Note Storage)] GmailMgr -->|API Calls| Gmail[(Gmail API)] TasksMgr -->|API Calls| Tasks[(Tasks API)] CalendarMgr -->|API Calls| Calendar[(Calendar API)] GitMgr -->|Git Operations| GitRepos[(Git Repositories)] MIST -->|Returns response| AI AI -->|Presents result| User

sequenceDiagram participant User participant AI as AI Assistant participant MIST as MIST Server participant Services as External Services User->>AI: "Send an email to John" AI->>MIST: MCP Request (action: sendEmail) MIST->>Services: Authenticate & API Call Services->>MIST: Response MIST->>AI: Structured Response AI->>User: "Email sent to John" User->>AI: "Take notes about my project" AI->>MIST: MCP Request (action: createNote) MIST->>Services: Store Note Services->>MIST: Confirmation MIST->>AI: Success Response AI->>User: "Notes saved successfully"

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

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

# Create a .env file with your configuration 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.envfile to set the correct paths for your environment.

The following environment variables can be set in your.envfile:

# Notes storage configuration MIST_NOTES_DIR=/path/to/notes/directory # Google API configuration MIST_GOOGLE_CREDENTIALS_PATH=./credentials.json MIST_GOOGLE_TOKEN_PATH=./token.json

Setting up Gmail, Calendar, and Tasks APIs

flowchart TD A[Start] --> B[Create Google Cloud Project] B --> C[Enable Required APIs] C --> D[Configure OAuth Consent Screen] D --> E[Create OAuth Credentials] E --> F[Download credentials.json] F --> G[Run MIST First Time] G --> H[Complete OAuth Flow] H --> I[OAuth Token Saved] I --> J[MIST Ready for Google Integration]

- Navigate to theGoogle Cloud Console
- Create a new project or select an existing one
- Give it a descriptive name (e.g., "MIST Integration")

uv run --with mcp[cli] --with-editable . mcp run mist/server.py

For production use, you may want to use a process manager likesystemd,supervisor, orpm2.

Add the following to your Claude Desktop settings:

{ "mcpServers": { "M.I.S.T.": { "command": "uv", "args": [ "run", "--with", "mcp[cli]", "--with-editable", "/path/to/mist", "mcp", "run", "/path/to/mist/server.py" ], "env": { "MIST_GOOGLE_CREDENTIALS_PATH": "/path/to/mist/credentials.json", "MIST_GOOGLE_TOKEN_PATH": "/path/to/mist/token.json", "MIST_NOTES_DIR": "/path/to/notes" } } } }

Add the following to your Zed editor settings:

"context_servers": { "mist-server": { "command": { "path": "uv", "args": [ "run", "--with", "mcp[cli]", "--with-editable", "/path/to/mist", "mcp", "run", "/path/to/mist/server.py" ], "env": { "MIST_GOOGLE_CREDENTIALS_PATH": "/path/to/mist/credentials.json", "MIST_GOOGLE_TOKEN_PATH": "/path/to/mist/token.json", "MIST_NOTES_DIR": "/path/to/notes" } }, "settings": { "enable_server": true } } }

When you first run the server, you'll need to authenticate with Google:

Below is a selection of commonly used Git tools. For a complete list and detailed parameters, please refer to theAPI Reference.

mist/ ├── __init__.py # Package initialization with version info ├── server.py # Main MCP server entry point ├── tools/ # Tool implementations │ ├── note_tools/ # Note management │ │ ├── __init__.py │ │ └── tool.py # Note tool implementations │ ├── gmail_tools/ # Gmail integration │ │ ├── __init__.py │ │ ├── config.py # Gmail-specific config │ │ ├── gmail.py # Gmail API utilities │ │ └── tool.py # Gmail tool implementations │ ├── calendar_tools/ # Calendar integration │ │ ├── __init__.py │ │ ├── calendar.py # Calendar API utilities │ │ ├── config.py # Calendar-specific config │ │ └── tool.py # Calendar tool implementations │ ├── tasks_tools/ # Tasks integration │ │ ├── __init__.py │ │ ├── config.py # Tasks-specific config │ │ ├── tasks.py # Tasks API utilities │ │ └── tool.py # Tasks tool implementations │ ├── git_tools/ # Git operations │ │ ├── __init__.py │ │ ├── config.py # Git-specific config (imports from google_api) │ │ ├── gitapi.py # Core Git command implementations │ │ └── tool.py # Git tool functions exposed to MCP │ ├── google_api/ # Common Google API utilities │ │ ├── __init__.py │ │ ├── client.py # Google API client │ │ └── config.py # Shared Google API config │ └── __init__.py # Tools package init ├── config_docs/ # Configuration documentation │ ├── api_reference.md # API reference documentation │ ├── configs.md # Example configuration templates │ ├── configuration_guide.md# Detailed configuration guide │ └── troubleshooting_guide.md # Troubleshooting guide ├── .github/ # GitHub configuration │ └── ISSUE_TEMPLATE/ # Issue templates for bug reports, etc. ├── LICENSE # MIT License ├── CONTRIBUTING.md # Contributing guidelines ├── README.md # Project documentation ├── pyproject.toml # Project metadata and dependencies ├── uv.lock # UV lock file for dependencies ├── credentials.json # Google API credentials (should be user-provided) └── .env # Environment configuration (user-created)

Contributions are welcome! Please see ourContributing Guidelinesfor details on how to get started.
- Fork the repository
- Create a feature branch:git checkout -b feature/amazing-feature
- Make your changes and commit them:git commit -m 'Add amazing feature'
- Push to your branch:git push origin feature/amazing-feature
- Open a pull request

This project is licensed under the MIT License - see theLICENSEfile for details.

- Model Context Protocolfor the protocol specification
- Google APIs for Gmail, Calendar, and Tasks integration

Hyper-fast, local Gmail and Google Calendar indexing for Claude Code, available as a Skill or MCP Server.