Contextforge MCP Server

ContextForge MCP — Persistent Memory for Claude, Cursor & Copilot

Give Claude Code, Cursor, and GitHub Copilot persistent memory across sessions via the Model Context Protocol (MCP). Stop re-explaining your project every time.

ContextForge MCP is an open-source MCP server that connects your AI coding assistants to long-term, searchable memory. Decisions, architecture notes, debugging context, and project knowledge stay available across every session — across every tool that supports MCP.

• 🧠 Persistent memory — your AI remembers everything across sessions, days, and weeks
• 🔍 Semantic search — find knowledge by meaning, not keywords
• 🔗 One memory, every tool — Claude Code, Cursor, Copilot, Claude Desktop, Windsurf
• 🐙 Git integration — sync commits and PRs automatically
• ✅ Task tracking — issues, assignments, and project status
• 👥 Team collaboration — share projects and memory with your team
• 🆓 Free tier — get started without a credit card

[!NOTE] Works automatically, no config needed (v0.5.1+). On connect, the server sends startup instructions to your AI client. Clients that honor them (Claude Desktop, Claude Code) load your project memory at the start of every session and save new decisions proactively — without you editing any settings. Running init (Step 4) is now a reinforcement, not a requirement, and still helps on clients that don't yet honor server instructions (e.g. Cursor).

---

Quick Start

1. Install

No install step needed — the setup below runs the server via npx -y contextforge-mcp, which fetches it on demand and keeps it up to date.

Prefer a global install for slightly faster cold starts? npm install -g contextforge-mcp is optional; if you do it, you can drop the npx -y prefix from the commands below.

2. Get your API key

1. Go to contextforge.dev
2. Sign up (free tier available)
3. Settings → API Keys → Generate API Key
4. Copy your key (starts with cf_)

3. Connect to your AI tool

Claude Desktop

Edit ~/Library/Application Support/Claude/claude_desktop_config.json:

{
  "mcpServers": {
    "contextforge": {
      "command": "npx",
      "args": ["-y", "contextforge-mcp"],
      "env": {
        "CONTEXTFORGE_API_KEY": "your-api-key-here"
      }
    }
  }
}

Restart Claude Desktop.

Claude Code (CLI)

claude mcp add contextforge -s user \
  -e CONTEXTFORGE_API_KEY=your-api-key-here \
  -- npx -y contextforge-mcp

Restart Claude Code and run /mcp to verify it's connected.

Cursor

Add to your Cursor MCP settings:

{
  "mcpServers": {
    "contextforge": {
      "command": "npx",
      "args": ["-y", "contextforge-mcp"],
      "env": {
        "CONTEXTFORGE_API_KEY": "your-api-key-here"
      }
    }
  }
}

GitHub Copilot (VS Code)

Add to your Copilot MCP config:

{
  "servers": {
    "contextforge": {
      "command": "npx",
      "args": ["-y", "contextforge-mcp"],
      "env": {
        "CONTEXTFORGE_API_KEY": "your-api-key-here"
      }
    }
  }
}

4. Initialize your project (recommended)

With v0.5.1+ the server auto-loads memory on supporting clients (see the note at the top), so this step is optional but recommended: it reinforces the behavior, covers clients that don't honor server instructions, and fully overrides the built-in file-based memory.

Set up your project so your AI editor always prefers ContextForge memory:

npx contextforge-mcp init

By default, init auto-detects which editor your project uses and writes three rule sections and one hook:

• Memory rules — route memory questions to ContextForge instead of the built-in file memory
• Session Presence rules — make parallel sessions check for each other at conversation start and before big changes
• Startup Context rules — load a short project summary (overview, open tasks, live sessions) from ContextForge at the start of every conversation
• Post-compaction recall hook (Claude Code only) — a SessionStart hook with matcher compact in .claude/settings.json. When Claude Code compacts a long conversation, the hook runs npx -y contextforge-mcp recall and re-injects your project's 10 most recent memories and pending tasks, so decisions saved in ContextForge survive the summary.

Files written:

• CLAUDE.md for Claude Code (signals: existing CLAUDE.md or .claude/ directory)
• .cursorrules for Cursor (signals: existing .cursorrules or .cursor/ directory)
• .claude/settings.json for Claude Code — merged, never overwritten; only the recall hook is added

If no editor is detected, both files are generated.

On clients that honor server instructions (Claude Desktop, Claude Code), ContextForge is used automatically even without this step. On other clients — or to guarantee the built-in file-based auto-memory never wins — run init: it writes explicit rules that always route memory to ContextForge.

Override with --editor

Re-running init is idempotent per section — sections you already have are left untouched; missing ones are appended. Upgrading from an older version? Just re-run npx contextforge-mcp init: it adds the new Startup Context section without touching the rest of your file.

Check your version

npx contextforge-mcp --version   # also: -v, version

Prints the installed version (e.g. contextforge-mcp 0.5.2).

Surviving compaction (Claude Code)

Long sessions get compacted: Claude Code summarizes the conversation to free space, and the summary keeps the gist but drops details — usually the decisions. init installs a hook that fires right after every compaction and prints your project's most recent ContextForge memories and pending tasks back into the context.

The hook runs as a plain shell command, so it reads your API key from CONTEXTFORGE_API_KEY if set, otherwise from the contextforge server entry in ~/.claude.json (where claude mcp add stores it), otherwise from a project .mcp.json. It needs a linked project (.contextforge in the repo root). If anything is missing it prints nothing and never blocks the session.

Try it by hand from your project directory:

npx contextforge-mcp recall

Already using ContextForge? (existing users)

Nothing to reconfigure. Update to the latest and restart your AI client:

npm update -g contextforge-mcp   # only if you installed globally; npx users get it on next launch

You do not need to re-run init for the auto-load behavior. To get the post-compaction recall hook, run npx contextforge-mcp init once in each project; it only adds what is missing.

---

Available Tools

ContextForge defines 69 tools across Knowledge Management, GitHub Integration, Issue Tracking, and Collaboration. No capability was ever removed — every tool below is fully callable — but as of v0.11.0, your AI client sees only 11 of them by default (CONTEXTFORGE_TOOLS=lean, the default):

• 10 core tools — the ones used on the agent's own initiative every session: memory_query, memory_ingest, memory_check_freshness, memory_confirm, memory_correct, memory_forget, tasks_list, tasks_what_next, session_list, memory_help.
• cf_tools — one gateway tool that discovers and runs the other 59. Ask your AI naturally ("sync my git commits", "restore from a snapshot", "olvida ese recuerdo viejo") and it searches (English or Spanish) and calls the right tool for you — no need to know an exact name.

Set CONTEXTFORGE_TOOLS=full to expose all 69 tools directly to your client instead, matching the behavior of versions before 0.11.0. See Environment Variables.

Why lean by default: 69 tool schemas cost ~15,000 tokens of context on every session, push past Cursor's 40-tool cap, and contribute to the accuracy degradation several clients show past ~50 tools. The lean set cuts that to ~3,500 tokens (~77% less) while keeping every tool one call away via cf_tools.

Knowledge Management

Spaces & Projects

GitHub Integration

Issue Tracking

Collaboration

Snapshots & Export

Utility

---

Session Presence (multi-session coordination)

Running several Claude Code sessions in parallel (worktrees, agent teams)? Each MCP process automatically registers itself as a live session and heartbeats while it runs. On a clean exit the session is removed at once (a detached helper delivers the goodbye even while the host process is being killed); if the process dies hard, the session expires ~10 minutes after its last heartbeat. Three tools let the agent coordinate — session_list is a core tool and always visible; session_update and session_end are reached through the cf_tools gateway by default (or set CONTEXTFORGE_TOOLS=full to see all three directly):

By default session_list is scoped to the current project — where work actually collides. In a multi-project organization, pass all_projects: true to see every session, or project: "<name-or-id>" to scope elsewhere.

Recommended pattern for your CLAUDE.md: call session_list when a conversation starts; call session_update when starting or switching tasks.

---

Natural Language Examples

You don't need to memorize commands — just talk naturally to your AI:

# Knowledge
"Save this: we use PostgreSQL for the main database"
"What database do we use?"
"List my spaces"

# GitHub
"Connect my repo github.com/myuser/myproject"
"What commits did I make today?"
"Show PRs merged this week"

# Issues
"Create an issue: Update the login page design"
"What's pending?"
"What should I work on next?"
"Mark the login issue as done"

---

Environment Variables

---

How it works

ContextForge MCP is a thin client that translates Model Context Protocol tool calls into authenticated HTTP requests against the ContextForge API. Your knowledge is stored, indexed (semantic embeddings), and retrieved on the server side — the MCP client itself is stateless.

This means:

• No infra to manage — no local databases, no embeddings to run, no vector stores to maintain
• Works everywhere your AI works — same memory across Claude Code, Cursor, Copilot, etc.
• Team collaboration — shared projects sync in real time

---

Dashboard

Manage your memory visually at contextforge.dev:

• View and organize your knowledge
• Search and filter memories
• Manage API keys and billing
• Track issues and collaborate
• Export and backup data

---

Development

# Clone and install
git clone https://github.com/alfredoizdev/contextforge-mcp.git
cd contextforge-mcp
npm install

# Build
npm run build

# Run tests
npm test

# Watch mode
npm run dev

---

Contributing

Issues and pull requests are welcome at github.com/alfredoizdev/contextforge-mcp.

---

Support

• 📖 Documentation
• 🐛 Report Issues
• 💬 Questions: support@contextforge.app

---

License

MIT © Alfredo Izquierdo