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

You log your daily activity using log_entry() → If you skip the mood, it’s auto-detected from your journal note.
You can check your weekly summary using summarize_week() → It shows total hours, frequent activity, and average mood.
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) |

MCP Servers