Overview

Goal Story MCP Server is a lightweight Model Context Protocol (MCP) server designed to help individuals and teams track, visualize, and iterate on goals and workflows. It combines progress tracking, timeline history, and chart visualizations so you can see how objectives evolve over time and make data-driven adjustments. The server exposes APIs for creating goals, recording progress events, and generating charts that summarize status and velocity.

This tool is useful when you want a structured but flexible way to manage goals—whether for personal habits, professional OKRs, or project milestones. It is intended for developers who want an extensible backend they can integrate into dashboards, chatbots, or productivity tools. The server is easy to run locally with Docker or in development mode, and it supports customizable workflows so you can model different goal lifecycles (e.g., tasks → milestones → epics).

Features

Goal CRUD: create, read, update, and delete goals and sub-goals
Progress events: record incremental updates with timestamps and metadata
Visualizations: generate charts (progress over time, completion rate, burn-down)
Custom workflows: define status transitions and fields for different goal types
REST API: simple endpoints for integration with UIs, bots, or automation scripts
Authentication and secrets support for private deployments
Export/import: CSV/JSON export of goal history for analysis

Installation / Configuration

There are two recommended ways to run the Goal Story MCP Server: using Docker (recommended for production or quick local setup) or running locally in development mode.

Quick clone:

git clone https://github.com/hichana/goalstory-mcp.git
cd goalstory-mcp

Run with Docker (recommended):

# start services using docker-compose
docker-compose up -d
# view logs
docker-compose logs -f app

Example docker-compose snippet (illustrative — check the repository for the canonical file):

version: '3.8'
services:
  app:
    build: .
    ports:
      - "8080:8080"
    environment:
      - PORT=8080
      - DATABASE_URL=postgres://user:pass@db:5432/goalstory
      - MCP_SECRET=change-this-secret
  db:
    image: postgres:13
    environment:
      - POSTGRES_DB=goalstory
      - POSTGRES_USER=user
      - POSTGRES_PASSWORD=pass
    volumes:
      - db-data:/var/lib/postgresql/data
volumes:
  db-data:

Run locally (development):

Inspect the repository to determine the runtime (Node.js or Python). Example checks:

# Node.js
ls package.json

# Python
ls pyproject.toml requirements.txt

2a. If Node.js:

npm ci
npm run migrate     # if DB migrations are provided
npm run dev         # start in development mode

2b. If Python:

python -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt
# apply migrations and run the app (framework-specific)

Environment variables to set (example):

PORT=8080
DATABASE_URL=postgres://user:pass@localhost:5432/goalstory
MCP_SECRET=super-secret-key
JWT_SECRET=jwt-signing-secret

Note: Always consult the repository README for exact commands and the definitive docker-compose file or start script.

Available Tools

The server exposes a REST API and a minimal web UI for visualization. Typical resources include:

Web UI: interactive dashboard to browse goals and charts
REST API: endpoints to manage goals and events
Export endpoints: download CSV/JSON of goal history
Chart endpoints: generate chart-ready datasets or rendered images

Common API endpoints (example):

Method	Path	Description
POST	/api/goals	Create a new goal
GET	/api/goals	List goals (filters supported)
GET	/api/goals/:id	Get goal details and progress events
POST	/api/goals/:id/events	Record progress event for a goal
GET	/api/charts/:type	Get chart data (e.g., progress/time)

Example: create a goal via curl

curl -X POST http://localhost:8080/api/goals \
  -H "Content-Type: application/json" \
  -d '{"title":"Write blog series","owner":"alice","targetDate":"2026-08-01"}'

Record progress:

curl -X POST http://localhost:8080/api/goals/123/events \
  -H "Content-Type: application/json" \
  -d '{"type":"progress","value":20,"notes":"wrote draft of post 1"}'

Use Cases

Personal habit tracking: Create a weekly exercise goal, record each workout as a progress event, and view a progress-over-time chart to keep momentum.
Team OKRs: Define quarterly objectives with numeric targets, have team members log contributions as events, and generate burn-down charts for stakeholder updates.
Project milestones: Track milestone completion percentage across sprints. Use exported CSVs to feed into reporting tools or analytics pipelines.
Coaching and mentoring: A coach can set client goals, monitor updates, and visualize progress during review sessions.
Research timelines: Track experiments, record results as events, and visualize cumulative progress toward publication or deadlines.

Contributing & Resources

For source code, issues, and contribution guidelines, see the repository on GitHub: https://github.com/hichana/goalstory-mcp. Look for documentation files and the repository README for up-to-date setup instructions, environment variable details, and API schema. If you plan to extend the server, consider adding SDK wrappers or automations that post progress events from other systems (e.g., CI

Goal Story MCP Server: Tracker & Visualization Tool