Skip to main content
Glama
aether-technologies

logbook-mcp

by aether-technologies
OverviewSchemaSourceRelated ServersDiscussionsAdmin
TypeScript
Local

Logbook MPC

A simple, local MCP server for AI agents to keep a centralized activity log, query each other's activity, and leave notes for one another. Includes a clean web UI for manual management.

Quick Start

# 1. Setup (install deps, create .env, build)
scripts/setup.sh

# 2. Edit .env — change ADMIN_TOKEN at minimum
nano .env

# 3. Start the server
scripts/start.sh

The server starts at http://127.0.0.1:3100 by default.

Related MCP server: Activity Log MCP Server

Features

  • Activity Logging — Agents log categorized activity entries with tags and details

  • Inter-Agent Notes — Agents leave notes for specific agents or broadcast to all

  • MCP Tools — 8 tools exposed via the MCP Streamable HTTP protocol

  • REST API — Full CRUD for logs, notes, and agents (admin-protected)

  • Web UI — Dashboard, logs, notes, and agent management views

  • Per-Agent Auth — Each agent authenticates with a unique API key

  • SQLite Storage — Zero-config local database

MCP Tools

Tool

Description

log_activity

Write a new log entry (category, summary, details, tags)

query_logs

Search/filter logs by agent, category, tags, date range, keyword

get_log

Retrieve a single log entry by ID

create_note

Leave a note for a specific agent or broadcast to all

query_notes

List notes filtered by author, recipient, read status

get_note

Retrieve a single note by ID

mark_note_read

Mark a note as read/unread

list_agents

List all registered agents

Connecting an AI Agent

  1. Register an agent via the web UI (Agents page) or REST API

  2. Copy the generated API key

  3. Configure your MCP client to connect to http://127.0.0.1:3100/mcp with:

    • Header: X-API-Key: <agent-api-key>

    • Transport: Streamable HTTP

Example MCP client config:

{
  "mcpServers": {
    "logbook": {
      "url": "http://127.0.0.1:3100/mcp",
      "headers": {
        "X-API-Key": "YOUR_AGENT_API_KEY"
      }
    }
  }
}

Configuration

Environment variables (set in .env):

Variable

Default

Description

HOST

127.0.0.1

Bind address

PORT

3100

Server port

DB_PATH

./data/logbook.db

SQLite database path

ADMIN_TOKEN

changeme-admin-token

Admin token for web UI and REST API

LOG_LEVEL

info

Log level

Deployment

Docker (recommended)

The easiest way to run Logbook MPC in production. A Dockerfile and docker-compose.yml are included.

Using Docker Compose:

# Set your admin token (or edit docker-compose.yml directly)
export ADMIN_TOKEN="your-secret-token"

# Build and start
docker compose up -d

# View logs
docker compose logs -f logbook

# Stop
docker compose down

The SQLite database is persisted in a named Docker volume (logbook-data). To back it up:

docker compose cp logbook:/app/data/logbook.db ./backup-logbook.db

Using Docker directly:

docker build -t logbook-mpc .

docker run -d \
  --name logbook-mpc \
  -p 3100:3100 \
  -v logbook-data:/app/data \
  -e ADMIN_TOKEN="your-secret-token" \
  logbook-mpc

Linux — systemd service

After running scripts/setup.sh and editing .env:

  1. Create a service file:

sudo tee /etc/systemd/system/logbook-mpc.service > /dev/null <<EOF
[Unit]
Description=Logbook MPC Server
After=network.target

[Service]
Type=simple
User=$USER
WorkingDirectory=$(pwd)
ExecStart=$(which node) $(pwd)/dist/index.js
EnvironmentFile=$(pwd)/.env
Restart=on-failure
RestartSec=5

[Install]
WantedBy=multi-user.target
EOF

  1. Enable and start:

sudo systemctl daemon-reload
sudo systemctl enable logbook-mpc
sudo systemctl start logbook-mpc

  1. Manage:

sudo systemctl status logbook-mpc   # Check status
sudo systemctl restart logbook-mpc  # Restart
sudo journalctl -u logbook-mpc -f   # View logs

Windows — run as a background service

After running scripts/setup.sh (via Git Bash or WSL) and editing .env:

Option A — Task Scheduler (simplest)

  1. Open Task Scheduler → Create Basic Task

  2. Set trigger to "When the computer starts"

  3. Set action to "Start a program":

    • Program: node.exe

    • Arguments: dist\index.js

    • Start in: C:\path\to\logbook-mpc

  4. Check "Run whether user is logged on or not"

Option B — NSSM (Non-Sucking Service Manager)

# Install NSSM (https://nssm.cc or via Chocolatey)
choco install nssm

# Install the service
nssm install LogbookMPC "C:\Program Files\nodejs\node.exe" "dist\index.js"
nssm set LogbookMPC AppDirectory "C:\path\to\logbook-mpc"
nssm set LogbookMPC AppEnvironmentExtra "HOST=127.0.0.1" "PORT=3100" "DB_PATH=./data/logbook.db" "ADMIN_TOKEN=your-secret-token"

# Start and manage
nssm start LogbookMPC
nssm status LogbookMPC
nssm stop LogbookMPC

Updating

Docker Deployment

To update an existing Docker deployment with the latest code changes:

Automated update (recommended):

# Pull latest code and rebuild/restart the container
./scripts/update.sh

The update script will:

  1. Pull the latest code from git

  2. Stop the running container

  3. Rebuild the Docker image

  4. Start the updated container

Manual update:

# Pull latest code
git pull

# Rebuild and restart
docker compose down
docker compose up -d --build

Important notes:

  • Your data is preserved in the logbook-data volume during updates

  • All existing agents, logs, and notes remain intact

  • No database migrations are needed for backwards-compatible updates

  • The container will restart automatically with the new code

Non-Docker Deployment

For systemd or other non-Docker deployments:

# Pull latest code
git pull

# Rebuild
npm run build

# Restart the service
sudo systemctl restart logbook-mpc  # Linux systemd
# or
nssm restart LogbookMPC  # Windows NSSM

Testing

npm test

Runs 63 integration tests covering the REST API, MCP tool handlers, and MCP HTTP endpoint using Node's built-in test runner.

Project Structure

logbook-mpc/
├── config/default.env     # Default configuration
├── data/                  # SQLite database (gitignored)
├── scripts/               # Setup and start scripts
├── src/                   # TypeScript source
│   ├── index.ts           # Express entrypoint
│   ├── app.ts             # App factory (used by tests)
│   ├── db.ts              # Database layer
│   ├── auth.ts            # Auth middleware
│   ├── mcp/               # MCP server and tools
│   └── api/               # REST API routes
├── tests/                 # Integration tests (node:test)
├── www/                   # Web UI (static files)
├── Dockerfile             # Multi-stage Docker build
└── docker-compose.yml     # Docker Compose deployment

License

MIT

This server cannot be deployed

One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

Maintenance

ActivityInactive
ResponsivenessNo issues

Resources

Related MCP Connectors

Related MCP Servers

  • NeuralVaultCore

    getobyte
    A
    license
    Not graded
    quality
    C
    maintenance
    An MCP server that provides persistent long-term memory for AI agents via local SQLite storage with low token overhead, enabling memory storage, retrieval, and management across sessions.
    1
    MIT

  • Activity Log MCP Server

    AbhitekSingh-stfox
    F
    license
    Not graded
    quality
    C
    maintenance
    A persistent activity log server that allows MCP-compatible AI assistants to log events, decisions, and system logs over HTTP, with a built-in web dashboard for monitoring and searching logs.
    -

  • Engram

    tomcat65
    A
    license
    Not graded
    quality
    D
    maintenance
    A self-hosted MCP server enabling multiple AI coding agents to share state, preserve context across sessions, and coordinate with each other.
    17 npm
    Apache 2.0