MCP Handley Lab Toolkit

⚠️ BETA SOFTWARE: This toolkit is in active development. While functional, APIs may change and some features may have rough edges. Issues and pull requests are welcome!

A toolkit that bridges AI assistants with command-line tools and services. Built on the Model Context Protocol (MCP), it enables AI models like Claude, Gemini, or GPT to interact with your local development environment, manage calendars, analyze code, and automate workflows through a standardized interface.

Requirements

• Python: 3.10 or higher
• MCP CLI: pip install mcp[cli] (for Claude Desktop integration)
• Package Manager: Either standard pip/venv or uv (optional, faster alternative)

System Dependencies (Optional)

Some tools require additional system packages:

• code2prompt tool: cargo install code2prompt
• email tools: msmtp, mutt, notmuch for email management

Quick Start

Get up and running in 5 minutes:

Standard Installation (venv)

# 1. Clone and enter the project
git clone [email protected]:handley-lab/mcp-handley-lab.git
cd mcp-handley-lab

# 2. Set up Python environment (requires Python 3.10+)
python3 -m venv venv
source venv/bin/activate

# 3. Install the toolkit (includes mcp[cli] automatically)
pip install -e .

# 4. Set up API keys and authentication
# Export in your .bashrc/.zshrc, a .env file, or the current session
export OPENAI_API_KEY="sk-..."
export GEMINI_API_KEY="AIza..."
export ANTHROPIC_API_KEY="sk-ant-..."
export GROQ_API_KEY="gsk_..."
export GROK_API_KEY="grok-..."
export GOOGLE_MAPS_API_KEY="AIza..."
# Note: Google Calendar requires OAuth setup (see tool description below)

# 5. Register essential tools with Claude (add others as needed)
# Note: Registering too many MCP tools can cause context bloat and reduce tool calling accuracy
# Only register the tools you actively need to maintain optimal performance

# Unified LLM tools (one tool handles all providers via model inference)
claude mcp add llm-chat --scope user mcp-llm-chat      # Chat with any LLM (Gemini, OpenAI, Claude, etc.)
claude mcp add llm-image --scope user mcp-llm-image    # Image generation (DALL-E, Imagen)
claude mcp add llm-models --scope user mcp-llm-models  # List available models

# Other essential tools
claude mcp add arxiv --scope user mcp-arxiv
claude mcp add google-maps --scope user mcp-google-maps

# Add additional tools as needed:
# claude mcp add llm-embeddings --scope user mcp-llm-embeddings  # Semantic embeddings
# claude mcp add llm-ocr --scope user mcp-llm-ocr                # Document OCR
# claude mcp add llm-audio --scope user mcp-llm-audio            # Audio transcription
# claude mcp add py2nb --scope user mcp-py2nb
# claude mcp add code2prompt --scope user mcp-code2prompt
# claude mcp add google-calendar --scope user mcp-google-calendar
# claude mcp add vim --scope user mcp-vim
# claude mcp add email --scope user mcp-email
# claude mcp add word --scope user mcp-word                        # Word document editing
# claude mcp add mathematica --scope user mcp-mathematica

# 6. Verify tools are working
# Use /mcp command in Claude to check tool status

Alternative Installation (uv)

uv is a fast Python package installer and environment manager. If you add the .venv/bin directory to your system PATH, the MCP tools can be called from anywhere without having to activate the virtual environment:

# 1. Clone and enter the project
git clone [email protected]:handley-lab/mcp-handley-lab.git
cd mcp-handley-lab

# 2. Set up Python environment and install (requires uv)
uv sync

# 3. Set up API keys and authentication
# Export in your .bashrc/.zshrc, a .env file, or the current session
export OPENAI_API_KEY="sk-..."
export GEMINI_API_KEY="AIza..."
export ANTHROPIC_API_KEY="sk-ant-..."
export GROK_API_KEY="grok-..."
export GOOGLE_MAPS_API_KEY="AIza..."
# Note: Google Calendar requires OAuth setup (see tool description below)

# 4. (Optional) Add venv bin directory to PATH for global access
# This allows MCP tools to be called from anywhere without activating venv
readlink -f .venv/bin
export PATH="/absolute/path/to/mcp-handley-lab/.venv/bin:$PATH"
# Add the above export line to your .bashrc or .zshrc for persistence

# 5. Register essential tools with Claude (add others as needed)
# Note: Registering too many MCP tools can cause context bloat and reduce tool calling accuracy
# Only register the tools you actively need to maintain optimal performance

# Unified LLM tools (one tool handles all providers via model inference)
claude mcp add llm-chat --scope user mcp-llm-chat      # Chat with any LLM
claude mcp add llm-image --scope user mcp-llm-image    # Image generation
claude mcp add llm-models --scope user mcp-llm-models  # List available models

# Other essential tools
claude mcp add arxiv --scope user mcp-arxiv
claude mcp add google-maps --scope user mcp-google-maps

# Add additional tools as needed:
# claude mcp add llm-embeddings --scope user mcp-llm-embeddings
# claude mcp add llm-ocr --scope user mcp-llm-ocr
# claude mcp add llm-audio --scope user mcp-llm-audio
# claude mcp add py2nb --scope user mcp-py2nb
# claude mcp add code2prompt --scope user mcp-code2prompt
# claude mcp add google-calendar --scope user mcp-google-calendar
# claude mcp add vim --scope user mcp-vim
# claude mcp add email --scope user mcp-email
# claude mcp add word --scope user mcp-word                        # Word document editing
# claude mcp add mathematica --scope user mcp-mathematica

# 6. Verify tools are working
# Use /mcp command in Claude to check tool status

Available Tools

🤖 Unified LLM Tools (llm-chat, llm-image, llm-embeddings, llm-ocr, llm-audio, llm-models)

Connect with multiple AI providers through unified interfaces

• llm-chat: Chat with any LLM - provider inferred from model name (e.g., gpt-5.2 → OpenAI, gemini-2.5-flash → Gemini)
• llm-image: Generate images with DALL-E, Imagen, or Grok
• llm-embeddings: Semantic embeddings for text (OpenAI, Gemini, Mistral)
• llm-ocr: Document OCR via Mistral
• llm-audio: Audio transcription via Mistral Voxtral
• llm-models: List all available models across providers
• Persistent conversations with memory via agent_name parameter
• Supported providers: OpenAI, Gemini, Claude, Mistral, Grok, Groq
• Claude example: > ask gpt-5.2 to review the changes you just made

📚 ArXiv (arxiv)

Search and download academic papers from ArXiv

• Search by author, title, or topic
• Download source code, PDFs, or LaTeX files
• Claude example: > find all papers by Harry Bevins on arxiv

📓 Python/Notebook Conversion (py2nb)

Convert between Python scripts and Jupyter notebooks

• Bidirectional Python ↔ Jupyter notebook conversion
• Preserve markdown comments and cell structure
• Claude example: > convert this Python script to a Jupyter notebook

🔍 Code Flattening (code2prompt)

Convert codebases into structured, AI-readable text

• Flatten project structure and code into markdown format
• Include git diffs for review workflows
• Claude example: > use code2prompt and gemini to look for refactoring opportunities in my codebase
• Requires: code2prompt CLI tool (cargo install code2prompt)

📅 Google Calendar (google-calendar)

Manage your calendar programmatically

• Create, update, and search events
• Find free time slots for meetings
• Claude example: > when did I last meet with Jiamin Hou?, and when would be a good slot to meet with her again this week?
• Requires: OAuth2 setup

🗺️ Google Maps (google-maps)

Get directions and routing information

• Multi-modal directions (driving, walking, cycling, transit)
• Real-time traffic awareness with departure times
• Alternative routes and waypoint support
• Claude example: > what time train do I need to get from Cambridge North to get to Euston in time for 10:30 on Sunday?
• Requires: Google Maps API key (GOOGLE_MAPS_API_KEY)

🧮 Mathematica (mathematica)

Execute Mathematica code and computations

• Run WolframScript commands and notebooks
• Perform symbolic and numerical calculations
• Generate plots and visualizations
• Export results in various formats
• Claude example: > use Mathematica to solve this differential equation and plot the solution
• Requires: WolframScript installed and licensed

✏️ Interactive Editing (vim)

Open vim for user input when needed

• Create or edit content interactively
• Useful for drafting emails or documentation
• Claude example: > use vim to open a draft of a relevant email

📧 Email Management (email)

Comprehensive email workflow integration

• Send emails with msmtp
• Compose, reply, and forward with Mutt
• Search and manage emails with Notmuch
• Contact management
• Claude example: > compose an email to the team about the project update
• Requires: msmtp, mutt, notmuch, and offlineimap installed and configured
• Microsoft 365 accounts: OAuth2 setup guide

📄 Word Documents (word)

Comprehensive Word document manipulation via pure OOXML

• Reading: Progressive disclosure (outline → blocks → full), search, metadata
• Content: Paragraphs, headings, tables, images (inline + floating), text boxes
• Formatting: Styles (create/edit/delete), runs, paragraph formatting, tab stops
• Tables: Add/delete rows/columns, merge cells, borders, shading, alignment
• Track Changes: Read revisions, accept/reject individual or all changes
• References: Bookmarks, captions, cross-references, TOC, footnotes/endnotes
• Bibliography: Add sources, insert citations, generate bibliography
• Comments: Add, reply, resolve/unresolve threaded comments
• Page Setup: Margins, orientation, columns, borders, sections, headers/footers
• Lists: Numbered/bulleted lists, promote/demote, restart numbering
• Other: Content controls, equations, hyperlinks, custom properties
• Claude example: > read the outline of my thesis, then add a citation to Smith2020 in the introduction

Recommended External MCPs

These MCP servers from other projects complement this toolkit:

MCP	Description	Installation
Playwright	Browser automation for web scraping and testing	npx @playwright/mcp@latest

See awesome-mcp-servers for a comprehensive list of available MCP servers.

Using AI Tools Together

You can use AI tools to analyze outputs from other tools. For example:

# 1. Use code2prompt to summarize your codebase
# Claude will run: mcp__code2prompt__generate_prompt path="/your/project" output_file="/tmp/summary.md"

# 2. Then ask any LLM to review it (provider inferred from model name)
# Claude will run: mcp__llm-chat__ask model="gemini-2.5-flash" prompt="Review this codebase" files=["/tmp/summary.md"]

This pattern works because:

• code2prompt creates a structured markdown file with your code
• The unified llm-chat tool can read files as context
• The provider is automatically inferred from the model name

Testing

This project uses pytest for testing. The tests are divided into unit and integration categories.

1. Install development dependencies:

   pip install -e ".[dev]"

2. Run all tests:

   pytest

3. Run only unit or integration tests:

   # Run unit tests (do not require network access or API keys)
   pytest -m unit
   
   # Run integration tests (require API keys and network access)
   pytest -m integration

Contributing

We welcome contributions! See CONTRIBUTING.md for detailed guidelines.

Quick start for contributors:

1. Fork and clone the repository
2. Create a feature branch
3. Make your changes following existing patterns
4. Run tests and linting: pytest && ruff check .
5. Bump version: python scripts/bump_version.py
6. Submit a pull request

License

MIT License - see LICENSE for details.