mcp-tasks-server

A small Model Context Protocol server that exposes a personal task tracker to any MCP-compatible client (Claude Desktop, Claude Code, custom agents). Tasks live in a local SQLite database; no cloud, no surprises.

This is a reference implementation of an MCP server that takes real write-actions on persistent state — the kind of integration you build between an agentic AI platform and an enterprise system, scaled down to a laptop.

Tools exposed

Tool	Effect on state
add_task	Insert a new task
list_tasks	Read; optional status filter
complete_task	Update status='done'
delete_task	Hard-delete a task
summarize_by_status	Read; aggregate counts

Each tool has a JSON schema declared in code, validated on every call.

Quick start

python -m venv .venv && source .venv/bin/activate
pip install -r requirements.txt
python server.py

Wire into Claude Desktop

Add to ~/Library/Application Support/Claude/claude_desktop_config.json:

{
  "mcpServers": {
    "tasks": {
      "command": "python",
      "args": ["/absolute/path/to/server.py"]
    }
  }
}

Then restart Claude Desktop. The tools appear in the MCP picker.

Sandbox / safety notes

• Database file lives at ~/.local/share/mcp-tasks/tasks.db by default; override with MCP_TASKS_DB. The path is normalized and confined to the user's home directory.
• delete_task requires the task ID to be an integer; no SQL is built from string concatenation. All queries use parameterized statements.
• The server has no network listeners — communication is over stdio per the MCP spec.

Sample tool calls

The full request/response shapes for every tool are in examples/tool-call-examples.md. Highlights:

Tool	Example call	Example result
add_task	{"title": "Review RFC", "notes": "..."}	{"id": 1, "title": "...", "status": "open"}
list_tasks	{"status": "open"}	{"tasks": [...]}
complete_task	{"id": 1}	{"id": 1, "status": "done"}
summarize_by_status	{}	{"counts": {"open": 2, "done": 1}}

Design notes

• Why SQLite? Embedded, transactional, present on every Python install. A real enterprise integration would target a service API; the contract on the agent side is identical.
• Why explicit JSON schemas? Some MCP clients display the schemas to the user before approving a tool call. Putting them inline in the server makes tool surfaces self-documenting and gives the LLM unambiguous parameter contracts.
• Why no auth? Personal/local server. For an enterprise MCP server you'd add OIDC token verification at the tool boundary and scope each tool to the calling principal's permissions.

License

MIT — see LICENSE.