aum-mcp-server

A personal MCP server split into focused servers — each loads only the tools it needs, keeping Claude's context lean.

Server	Tools
aum-developer	Web/HTTP, file system, shell, GitHub, Ollama
aum-notes	Persistent notes, Word (.docx), PowerPoint (.pptx)
aum-communication	Gmail, Google Calendar, Google Contacts, iMessage
aum-canvas	Canvas LMS — courses, grades
aum-personal	Spotify
aum-slurm	SLURM job management via SSH (any HPC cluster)

---

Setup

1. Install dependencies

npm install

2. Configure environment

cp .env.example .env

Fill in .env with your API keys. Each section in .env.example explains where to generate them.

Google (Gmail + Calendar + Contacts) requires an OAuth flow — after filling in GOOGLE_CLIENT_ID and GOOGLE_CLIENT_SECRET, run:

node --env-file=.env scripts/google-auth.mjs

This prints a GOOGLE_REFRESH_TOKEN — paste it into .env. One token covers all three Google services.

3. Build

npm run build

4. Register with Claude

Add to ~/.mcp.json (create it if it doesn't exist). Replace /path/to/mcp-server with the absolute path to this repo:

{
  "mcpServers": {
    "aum-developer": {
      "command": "node",
      "args": [
        "--env-file=/path/to/mcp-server/.env",
        "/path/to/mcp-server/dist/developer.js"
      ]
    },
    "aum-notes": {
      "command": "node",
      "args": [
        "--env-file=/path/to/mcp-server/.env",
        "/path/to/mcp-server/dist/notes-server.js"
      ]
    },
    "aum-communication": {
      "command": "node",
      "args": [
        "--env-file=/path/to/mcp-server/.env",
        "/path/to/mcp-server/dist/communication.js"
      ]
    },
    "aum-canvas": {
      "command": "node",
      "args": [
        "--env-file=/path/to/mcp-server/.env",
        "/path/to/mcp-server/dist/canvas-server.js"
      ]
    },
    "aum-personal": {
      "command": "node",
      "args": [
        "--env-file=/path/to/mcp-server/.env",
        "/path/to/mcp-server/dist/personal.js"
      ]
    },
    "aum-slurm": {
      "command": "node",
      "args": [
        "--env-file=/path/to/mcp-server/.env",
        "/path/to/mcp-server/dist/slurm.js"
      ]
    }
  }
}

You can register only the servers you need — each one is independent.

---

Tool reference

<details> <summary>aum-developer</summary>

Tool	Description
fetch_url	Fetch any URL (GET/POST/PUT/PATCH/DELETE)
http_status	Check HTTP status without downloading body
call_api	Call JSON APIs with automatic serialization
read_file	Read file contents
write_file	Write content to a file
list_directory	List files/dirs (optional recursive)
system_info	Hostname, platform, memory, architecture
current_datetime	Current date/time in any IANA timezone
run_command	Execute shell commands
get_env	Read environment variables
github_contributions	Contribution calendar and stats for the past N days
github_profile	Profile info — repos, followers, top starred repos
ollama_models	List installed Ollama models ranked by tool-use capability
ollama_chat	Agentic chat with best local model — routes to relevant tools automatically

</details>

<details> <summary>aum-notes</summary>

Tool	Description
note_set	Save a persistent note by key
note_get	Retrieve a note by key
note_list	List all saved note keys
note_delete	Delete a note by key
word_read	Extract text from a .docx file
word_create	Create a .docx file from headings, paragraphs, and bullets
ppt_read	Extract slide text from a .pptx file
ppt_create	Create a .pptx file from a list of slides

</details>

<details> <summary>aum-communication</summary>

Tool	Description
gmail_inbox	List recent Gmail inbox messages
gmail_search	Search Gmail by query
gmail_get_message	Read a full email message
gmail_send	Send an email
calendar_list	List available Google Calendars
calendar_events	List upcoming calendar events
calendar_today	Get today's events
calendar_create_event	Create a new calendar event
contacts_search	Search Google Contacts by name or email
contacts_get	Get full details for a specific contact
contacts_list	List all contacts
imessage_search	Search messages by contact or content
imessage_recent	Get most recent messages across all chats
imessage_chat	Get messages from a specific conversation
imessage_contacts	List all iMessage contacts with last message
imessage_send	Send an iMessage via Messages.app

</details>

<details> <summary>aum-canvas</summary>

Tool	Description
canvas_courses	Active courses with current grades and scores

</details>

<details> <summary>aum-personal</summary>

Tool	Description
spotify_now_playing	Currently playing track
spotify_recent	10 most recently played tracks
spotify_top_artists	Top artists over the past ~6 months

</details>

<details> <summary>aum-slurm</summary>

Tool	Description
slurm_run	Run a shell command on the HPC cluster via SSH
slurm_jobs	List SLURM jobs in the queue
slurm_files	List files in a remote directory
slurm_read_file	Read a file from the HPC cluster
slurm_submit_job	Submit a SLURM batch job script
slurm_storage	Check disk quota and storage usage

</details>

---

Ollama (local LLM)

ollama_chat runs a fully local agentic loop — no cloud required.

Prerequisites: Ollama installed and running, with at least one model pulled.

ollama pull qwen2.5     # recommended — best tool use, fast
ollama pull llama3.2    # solid alternative
ollama serve            # start if not running as a service

ollama_chat automatically selects a focused subset of tools based on keywords in your prompt. Destructive tools (write_file, run_command, gmail_send, etc.) are never auto-routed — pass them explicitly via the tools parameter.

---

Dashboard

A local web UI runs at http://localhost:4242 with server status, registered tools, API integration cards, and a notes viewer/editor.

npm run web

---

Development

npm run build                # compile all servers to dist/
npm run dev:developer        # run developer server with tsx
npm run dev:notes            # run notes server with tsx
npm run dev:communication    # run communication server with tsx
npm run dev:slurm            # run slurm server with tsx
npm run web                  # local dashboard

Always run npm run build after making changes before restarting Claude.

---

Adding a new tool

1. Create src/tools/mytool.ts:

import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
import { z } from "zod";

export function registerMyTools(server: McpServer) {
  server.tool("my_tool", "What it does", {
    param: z.string().describe("A parameter"),
  }, async ({ param }) => {
    return { content: [{ type: "text" as const, text: `result` }] };
  });
}

2. Import and call in the relevant entry point (src/developer.ts, src/notes-server.ts, etc.).

3. Add to the TOOLS array in src/web.ts for the dashboard.

4. Run npm run build.

---

Notes storage

Notes are persisted at ~/.aum-mcp/notes.json.