Skip to main content
Glama
Personal Workspace MCP Server

Personal Workspace MCP Server

by Jemade

Personal Workspace MCP Server

M8ven Score

A Python MCP server that gives an AI assistant three practical capabilities: manage personal tasks, answer questions from a local SQLite database, and retrieve weather forecasts.

The server uses the official Model Context Protocol Python SDK. Natural-language interpretation happens in your MCP client: the assistant reads the schema, selects a tool and supplies validated arguments. This project does not contain a hidden chatbot or require an LLM API key.

What it does

  • Tasks: create, search, filter, update, complete, archive and restore tasks. SQLite persists data between sessions. Version checks prevent stale updates, and every change records an audit event.

  • Database questions: expose a configured SQLite database through schema resources and bounded read-only queries. Only explicitly allowed tables are visible.

  • Weather: search locations and retrieve current modeled weather plus up to seven forecast days from Open-Meteo. Results retain units, source and retrieval time.

Example requests in an MCP-capable assistant:

Create a high-priority task to review my assignment, due on 2026-10-10.

Show unfinished tasks due before 2026-10-12.

How many tasks do I have in each status?

Find Harare in Zimbabwe and show the next three days of weather.

Which sample courses have more than 12 credits?

Related MCP server: Expense Tracker MCP Server

Quick start

Requires Python 3.11 or newer.

git clone https://github.com/Jemade/MCP-SERVER.git
cd MCP-SERVER
python -m venv .venv
source .venv/bin/activate
# Windows PowerShell: .venv\Scripts\Activate.ps1
python -m pip install -e ".[dev]"
python examples/smoke_client.py

Start the server:

personal-mcp --task-db ./data/tasks.db

The server communicates over stdio. Waiting silently for client messages is normal; it is not a browser application. Connect it to an MCP client to interact.

Connect an AI assistant

For clients supporting the common mcpServers configuration, use absolute paths. Replace the example paths with your actual checkout and Python executable.

{
  "mcpServers": {
    "personal-workspace": {
      "command": "/absolute/path/MCP-SERVER/.venv/bin/python",
      "args": ["-m", "personal_mcp.server"],
      "env": {
        "TASK_DB_PATH": "/absolute/path/MCP-SERVER/data/tasks.db"
      }
    }
  }
}

On Windows, use the absolute .venv\\Scripts\\python.exe path and escaped backslashes in JSON. Restart the client after editing its configuration. Exact configuration locations vary by client.

You can also inspect the server without an LLM:

npx -y @modelcontextprotocol/inspector .venv/bin/python -m personal_mcp.server --task-db ./data/tasks.db

Approve task mutations in your client. Tool annotations and prompts guide the client, but approval enforcement belongs to the host application.

Query a separate SQLite database

Create the demonstration database:

python examples/create_sample_database.py
personal-mcp --task-db ./data/tasks.db --query-db ./data/sample_courses.db --tables courses

The catalog is fictional sample data, not an official University of Zimbabwe catalog. You can substitute an existing database and a comma-separated allowlist such as --tables courses,departments.

For a configured client, add:

{
  "QUERY_DB_PATH": "/absolute/path/MCP-SERVER/data/sample_courses.db",
  "QUERY_ALLOWED_TABLES": "courses"
}

Read database://schema first, then query with placeholders:

SELECT code, title, credits FROM courses WHERE credits > ? ORDER BY code

Pass parameters: [12]. The returned columns correspond positionally to each array in rows. If truncated is true, narrow the query or aggregate results before answering.

Tool reference

Tool

Purpose

create_task

Create a task with optional deadline and priority

list_tasks

Filter and paginate tasks

get_task

Read one task and its current version

update_task

Change supplied fields with an expected version

archive_task

Hide a task without deleting it

restore_task

Restore an archived task

task_history

Read the latest 100 audit events

database_schema

Describe allowlisted tables

query_database

Execute one bounded read-only query

search_locations

Return up to five candidate locations

weather_forecast

Fetch weather for selected coordinates

Resources: database://schema, tasks://overview.

Prompts: plan_day(day), analyze_database(question).

Task statuses: todo, in_progress, done. Priorities: low, medium, high. Deadlines use YYYY-MM-DD; audit timestamps use UTC. To remove a deadline, call update_task with clear_due_date: true.

Architecture

flowchart TD
    A["MCP client and AI assistant"] --> B["Python MCP server over stdio"]
    B --> C["Task tools"]
    B --> D["Read-only SQL tools"]
    B --> E["Weather tools"]
    C --> F["Task SQLite file and audit events"]
    D --> G["Allowlisted SQLite tables"]
    E --> H["Open-Meteo APIs"]

The task database and query database can be the same file or separate files. Weather is the only outbound integration. No frontend, remote account system or public HTTP endpoint is included.

Safety and operating limits

  • Task SQL uses bound parameters. Task updates use optimistic concurrency.

  • Query connections open in read-only mode. A SQLite authorizer rejects writes, PRAGMAs, attachments, access to other tables and unapproved functions. Arbitrary views and recursive queries are not supported.

  • Queries are limited to 10,000 SQL characters, 200 rows, roughly 100 KB of serialized row data and a one-second execution budget. SQLite value size is capped at 1 MB.

  • Weather requests use fixed HTTPS endpoints, a ten-second timeout, bounded response bodies, up to three attempts for temporary failures and a five-minute cache.

  • The cache is per process, holds at most 128 entries and is not a distributed quota system.

  • This is a single-user local server. It inherits the permissions of the user running it. It is not a sandbox for executing code and should not be published as an unauthenticated remote service.

  • Allowlisting tables exposes all readable columns in those tables. Use a sanitized database when some columns contain information you do not want to share with your assistant.

  • Treat database text and API results as untrusted data. The prompts advise this, but they cannot guarantee an AI client will resist prompt injection.

  • Back up task data with SQLite's backup API or stop the process before copying the database and associated WAL files.

Weather provider

Open-Meteo's public API does not require a key for its free noncommercial service. Review its current terms and subscription requirements before commercial use. Display attribution when presenting forecasts. The server returns modeled weather, not a guarantee of observed conditions.

Sources:

Development and verification

ruff check .
pytest -q
python examples/smoke_client.py

Tests cover task persistence, stale and concurrent updates, input validation, table authorization, blocked SQL operations, output limits, HTTP errors, retries, caching and MCP discovery. The smoke client starts a real stdio subprocess and exercises tool calls, resources, prompts and write rejection.

CI runs on Python 3.11, 3.12 and 3.13. Network calls in unit tests use an HTTP mock transport; live provider availability is separate.

The dependency range intentionally targets the SDK v1 maintenance line (mcp<2) and is tested against 1.30.0. Upgrading to v2 requires adapting and rerunning the protocol tests. See the official SDK documentation.

Troubleshooting

  • No terminal output: stdio servers wait for an MCP client. Run the smoke client or Inspector.

  • Database does not exist: the task database is created automatically; an external query database must already exist.

  • Query rejected: inspect the schema and use one SELECT over allowlisted tables and approved functions.

  • Version conflict: call get_task, review the newer values and retry with its current version.

  • Weather unavailable: check network connectivity and retry later. Local task tools continue working independently.

  • Client cannot import the package: use the exact virtual-environment Python where you installed this project.

License

MIT. See LICENSE.

Contributing

See CONTRIBUTING.md for development checks, regression tests and review expectations. Use the issue templates for reproducible bugs or concrete feature proposals.

Engineering and contribution guide

Read the engineering notes for implementation boundaries and verification commands, the review checklist for evidence still required, and CONTRIBUTING.md to propose changes. Report vulnerabilities through SECURITY.md.

Repository hygiene

Available Tools

11 tools
archive_taskB

Archive a task without deleting its data or history.

Inputs: task_id (required), expected_version (required).

create_taskC

Create a task. due_date is an optional YYYY-MM-DD calendar date.

Inputs: title (required), due_date, priority, description.

database_schemaA
Read-only

Describe the configured allowlisted SQLite tables before composing SQL.

Inputs: no named parameters.

get_taskB
Read-only

Read one task, including its version for optimistic updates.

Inputs: task_id (required).

list_tasksC
Read-only

Filter tasks with pagination. Search matches title or description.

Inputs: limit, offset, search, status, +3 more.

query_databaseA
Read-only

Execute one read-only SELECT query. Use ? placeholders and parameters for values.

Inputs: sql_query (required), max_rows, parameters.

restore_taskC

Restore an archived task.

Inputs: task_id (required), expected_version (required).

search_locationsB
Read-only

Find weather locations. Return candidates; clarify ambiguous place names.

Inputs: name (required), country_code.

task_historyA
Read-only

Read up to 100 recent audit events for a task.

Inputs: task_id (required). Returns: result

update_taskC

Update supplied fields using the current version. clear_due_date removes a deadline.

Inputs: task_id (required), expected_version (required), title, status, +4 more.

weather_forecastB
Read-only

Retrieve current modeled weather and daily forecasts from Open-Meteo.

Inputs: latitude (required), longitude (required), days.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    A3.5/5.0

    Scored across 11 tools

    Disambiguation5/5

    Every tool targets a distinct resource and action: task CRUD is well-separated from history, database schema is distinct from query execution, and location search is distinct from weather forecast. No two tools could be easily confused.

    Naming Consistency4/5

    Most tools follow a clear verb_noun snake_case pattern (get_task, create_task, list_tasks, update_task, archive_task, restore_task, query_database, search_locations). A few tools use noun_noun instead (task_history, database_schema, weather_forecast), which is a minor deviation.

    Tool Count5/5

    11 tools across three sub-domains (tasks, database, weather) is well-scoped; each tool has a clear, non-redundant role and the count is appropriate for the server's purpose.

    Completeness5/5

    Task lifecycle is fully covered (create, read, update, archive, restore, history), database access is complete for read-only queries (schema + SELECT), and weather covers both location search and forecasting.

    Maintenance

    ActivitySlowing
    ResponsivenessOutdated data

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      Not graded
      quality
      D
      maintenance
      Enables AI assistants to answer real-world weather questions using live Open-Meteo data, with tools for current conditions, umbrella reasoning, outdoor suitability, and city comparisons.
      MIT
    • A
      license
      Not graded
      quality
      D
      maintenance
      Enables Claude to query a local SQLite database read-only, search and read files within a sandboxed directory, and get current weather and forecasts via Open-Meteo, all through natural language.
      MIT