MCP Console

A self-hosted context server for AI coding agents. It stores your project docs, coding skills and per-branch task plans as plain markdown, serves them to Claude Code (or any MCP client) over the Model Context Protocol, and gives you a web console to browse and edit everything.

• Projects — documentation pages agents load on demand (index, architecture, deploy, …)

• Tasks — one markdown plan per git branch, with an active → pending → history lifecycle, so an agent can resume where the last session stopped

• Skills — team conventions agents load only when relevant (progressive disclosure keeps token use low)

• Templates — per-stack scaffolds used when creating a new project

• Knowledge base — self-contained HTML landing pages / explainers

Built with Nuxt 4, Nuxt UI, Nuxt Content and the official MCP TypeScript SDK. Content lives on disk under content/ — no database to migrate, easy to back up or keep in git.

Quick start

Requires Node 22+ and pnpm.

pnpm install
cp .env.example .env      # set MCP_USERNAME / MCP_PASSWORD (and MCP_TOKEN)
pnpm dev                  # console: http://localhost:3000  ·  MCP: http://localhost:3000/mcp

Sign in with the credentials from .env. The repo ships with example content (example-app project, two skills, one landing) so every screen has something to show.

Connect Claude Code

Copy .mcp.json.example to .mcp.json in the repo you want agents to work in (or run the CLI equivalent):

claude mcp add --transport http mcp-console http://localhost:3000/mcp \
  --header "Authorization: Bearer $MCP_TOKEN"

Then tell the agent how to use it, e.g. in that repo's CLAUDE.md:

## Session start
1. `get_project_context("my-project", "index")`
2. `list_skills` — load only the skills relevant to the task
3. `get_task("my-project", "<current git branch>")` — if missing, `upsert_task` with a plan
4. As you work: `check_task_item`, `append_to_task` for lessons
5. When the branch merges: `set_task_status(..., "history")`

Related MCP server: data-olympus MCP server

Configuration

Content layout

content/
├── projects/<project>/
│   ├── index.md, architecture.md, deploy.md, …   # doc pages
│   └── tasks/{current,pending,history}/<branch>.md
├── skills/<skill>/
│   ├── skill.md                # frontmatter: name + description ("Use when …")
│   └── references/*.md         # optional deep-dive material
├── templates/{projects,skills}/<stack>.md        # {{project}} {{stack}} {{description}}
└── landings/<slug>.html        # served at /landings/<slug>

To start fresh, delete content/projects/example-app, content/skills/example-skill and content/landings/welcome.html, then create your own project from the console (New project) or with the init_project tool.

Content is tracked in git by default. If the deployed server is your source of truth (agents write to it), see the commented lines at the bottom of .gitignore.

MCP tools

Project pages are also exposed as MCP resources at doc://<project>/<page>.

Deployment

Docker

docker build -t mcp-console .
docker run -d --name mcp-console --restart unless-stopped \
  -p 127.0.0.1:3000:3000 --env-file .env \
  -v "$PWD/content:/app/content" \
  -v mcp-console-data:/app/data \
  mcp-console

Or with Compose:

services:
  mcp-console:
    build: .
    restart: unless-stopped
    env_file: .env
    ports:
      - "127.0.0.1:3000:3000"
    volumes:
      - ./content:/app/content      # docs, tasks, skills, landings
      - mcp-console-data:/app/data  # login sessions (SQLite)
volumes:
  mcp-console-data:

Deployment notes

• Set MCP_TOKEN before exposing the server. Without it /mcp is open to anyone and includes destructive tools (delete_project, write_skill, …). Use a strong MCP_PASSWORD too — generate both with openssl rand -hex 32.

• Serve over HTTPS. The session cookie is Secure in production, so console login does not work over plain HTTP. Bind the container to 127.0.0.1 (as above) and put a reverse proxy in front. Caddy is the shortest path:

  mcp.example.com {
      reverse_proxy 127.0.0.1:3000
  }

  With nginx, disable buffering for the MCP endpoint — it streams responses over SSE: proxy_buffering off; proxy_read_timeout 1h; plus proxy_http_version 1.1;.

• Persist content/. Agents write docs, tasks and skills at runtime; without the volume those edits are lost on the next rebuild. The image bakes in the repo's content/ only as a starting point — a bind mount replaces it.

• Back up content/ — it is the only state that matters (plain files; rsync, a cron'd git commit, or volume snapshots all work). data/sessions.db only holds login sessions; losing it just signs everyone out.

• Build needs ~4 GB RAM. The Dockerfile raises Node's heap for the Nuxt build. On a small VPS, build the image in CI (or locally) and pull it instead.

• Run a single instance. MCP sessions are kept in process memory, so don't load-balance across replicas. After a restart, clients re-initialize automatically.

• Without Docker: pnpm install && pnpm build, then node --env-file=.env .output/server/index.mjs from the repo root (the server resolves content/ and data/ relative to the working directory). Use systemd or pm2 to keep it running.

Development

pnpm test     # vitest unit tests
pnpm build    # production build → .output/

The Claude page in the console browses your local ~/.claude folder. It is dev-only and returns 404 in production builds.

License

MIT