FocusPal Local MCP Server

🧠 FocusPal — AI Productivity & Mood Tracker (Local MCP Server)

FocusPal is a local MCP (Model Context Protocol) server built using FastMCP. It helps you log daily productivity, detect mood automatically, summarize progress, and get AI-powered improvement suggestions — all inside Claude Desktop.

---

🧩 Features

✅ Log your daily focus or study sessions ✅ Auto-detect mood using TextBlob sentiment analysis ✅ Summarize weekly productivity stats ✅ Get personalized AI suggestions for better focus ✅ Lightweight local database using SQLite (no internet needed)

---

⚙️ Installation

1. Clone the repository

git clone https://github.com/rishu5kumar/FocusPal-Local-MCP-Server.git
cd FocusPal-Local-MCP-Server

2. Install dependencies

Make sure you have uv installed and initialized. Then run:

uv add fastmcp textblob numpy

---

🚀 Running FocusPal as a Local MCP Server

Since this is a local MCP server, it uses STDIO transport. That means it runs directly on your system and connects locally to Claude Desktop.

🧠 To connect FocusPal to Claude Desktop:

Run this once in your project folder:

uv run fastmcp install claude-desktop main.py

This command:

• Starts your local MCP server (FocusPal)
• Automatically registers it inside Claude Desktop
• Claude can now use FocusPal tools in chats

✅ Once installed, you’ll see FocusPal listed under Claude → Settings → Tools → Installed MCP Servers.

---

🔍 Development & Testing

To test your MCP server with MCP Inspector (before installing):

uv run fastmcp dev main.py

Then open the MCP Inspector (from the FastMCP app or CLI) and enter the default URL:

http://127.0.0.1:6274/mcp

You’ll see your tools live — like:

• log_entry(date, hours, activity, mood, note)
• summarize_week(start_date, end_date)
• suggest_improvement(start_date, end_date)

---

💬 Example Commands in Claude

After connecting FocusPal to Claude, you can say things like:

🗓️ “FocusPal, log that I studied for 2.5 hours today and felt tired.” 📊 “FocusPal, summarize my productivity from 2025-11-01 to 2025-11-07.” 💡 “FocusPal, suggest improvements for this week’s focus.”

---

📂 Project Structure

focuspal/
├── main.py              # Main MCP server script
├── focuspal.db          # SQLite database (auto-created)
├── README.md            # You’re here
└── pyproject.toml

---

🧱 Tech Stack

• FastMCP – To easily create MCP servers
• SQLite – For local data storage
• TextBlob – For AI-based mood sentiment analysis
• NumPy – For mood statistics and averages

---

🧠 How It Works

1. You log your daily activity using log_entry() → If you skip the mood, it’s auto-detected from your journal note.

2. You can check your weekly summary using summarize_week() → It shows total hours, frequent activity, and average mood.

3. You can ask for AI tips via suggest_improvement() → It gives suggestions based on your mood & average working hours.

---

🧰 Example Code Snippet

uv run fastmcp install claude-desktop main.py

Then in Claude:

“FocusPal, summarize_week('2025-11-01', '2025-11-07')”

---

🧑‍💻 Developer Notes

• If you modify main.py, rerun:

  uv run fastmcp install claude-desktop main.py
  

  to update Claude with the latest version.

• No internet or authentication is required — it’s 100% local.

• To remove it, go to Claude → Settings → Tools → Installed MCP Servers → Remove FocusPal.

---

🏁 Summary

Command	Purpose
uv run fastmcp dev main.py	Test locally with MCP Inspector
uv run fastmcp install claude-desktop main.py	Register local server with Claude
uv run fastmcp run main.py	Run normally (without inspector)

---