MCP Project Context Server

A Model Context Protocol (MCP) server that provides persistent project context and planning state between Claude Code sessions. This eliminates the need to re-explain project details, current status, and development context every time you start a new coding session.

What It Does

The MCP Project Context Server acts as a persistent memory layer for your development projects, maintaining:

Project Information: Name, description, current phase, and status
Technology Stack: Frontend, backend, database, infrastructure, and tooling choices
Task Management: Development tasks with priorities, status tracking, and dependencies
Decision History: Architectural and technical decisions with reasoning
Session Continuity: Goals, achievements, and blockers from previous sessions
Development Notes: Important observations and insights

How It Works

The server implements the Model Context Protocol to provide Claude Code with tools for managing project context:

Project Creation: Initialize new projects with tech stack and current phase
Context Retrieval: Get comprehensive project state and history
Task Management: Create, update, and track development tasks
Decision Recording: Document important technical and architectural decisions
Session Tracking: Maintain continuity between development sessions
Note Taking: Capture important insights and observations

Data is stored as JSON files in a local data directory, making it easy to backup, version control, or inspect manually.

Key Features

Persistent Context: Project state survives between Claude Code sessions
Technology Stack Awareness: Tracks your preferred technologies and tools
Task Prioritization: Organize work with priority levels and status tracking
Decision Documentation: Maintain architectural decision records (ADRs)
Session Goals: Track what you planned vs what you achieved
File-Based Storage: Simple JSON storage that's easy to understand and backup

Prerequisites

Node.js 18 or higher
pnpm package manager
Claude Code CLI tool

Installation

Clone and setup the project:

git clone <repository-url>
cd mcp-project-context
pnpm install

Build the server:

pnpm run build

Make the server executable:

chmod +x dist/index.js

Configuration

Claude Code Setup

Create or edit the Claude Code MCP configuration file:

mkdir -p ~/.claude

Add your server configuration to `~/.claude.json:

{
    "mcpServers": {
      "mcp-project-context": {
        "type": "stdio",
        "command": "/path/to/mcp-project-context/dist/index.js",
        "args": [],
        "env": {}
      }
    }
}

Replace /absolute/path/to/your/mcp-project-context with the actual path to your project directory.

Verify the configuration:

cat ~/.claude/mcp.json

Usage

Once configured, Claude Code will automatically start and connect to your MCP server. You can then use natural language to interact with your project context:

Example Commands

Create a new project:

"Create a new project called 'E-commerce Platform' for building a modern online store using Next.js, Node.js, PostgreSQL, and Docker"

Get current project status:

"What's the current status of my project? Where did we leave off?"

Add development tasks:

"Add a high-priority task to implement user authentication with OAuth"

Record architectural decisions:

"Record that we decided to use Prisma as our ORM because it provides better TypeScript support and easier migrations"

Update task status:

"Mark the authentication task as completed"

Add project notes:

"Add a note that the API rate limiting is causing issues in development"

Available Tools

The server provides these tools to Claude Code:

create_project - Initialize a new project with tech stack and description
get_project_context - Retrieve comprehensive project state and history
list_projects - Show all projects ordered by last access
add_task - Create new development tasks with priorities
update_task - Modify task status, priority, or details
add_note - Capture important observations and insights
record_decision - Document architectural and technical decisions
start_session - Begin a development session with specific goals

Data Storage

Project data is stored in the data directory:

data/
├── projects/
│   ├── project-uuid-1.json
│   ├── project-uuid-2.json
│   └── project-uuid-3.json
└── sessions/
    ├── session-uuid-1.json
    ├── session-uuid-2.json
    └── session-uuid-3.json

Each file contains structured JSON data that you can inspect or backup as needed.

Development

Project Structure

mcp-project-context/
├── src/
│   ├── index.ts              # Entry point
│   ├── server.ts             # MCP server implementation
│   ├── storage/
│   │   ├── project-store.ts  # File-based storage layer
│   │   └── context-manager.ts # Context management logic
│   └── types/
│       └── project-types.ts  # TypeScript type definitions
├── data/                     # Project data storage
├── package.json
├── tsconfig.json
└── README.md

Available Scripts

pnpm run build - Compile TypeScript to JavaScript
pnpm run start - Run the compiled server
pnpm run dev - Run in development mode with auto-reload

Testing the Server

You can test the server manually:

# Start the server directly
node dist/index.js

# The server will wait for MCP protocol messages via stdin

For interactive testing, use the MCP Inspector:

npx @modelcontextprotocol/inspector node dist/index.js

Troubleshooting

Server Connection Issues

Verify the server builds successfully:

pnpm run build

Check that the executable bit is set:

ls -la dist/index.js
chmod +x dist/index.js

Test the server manually:

node dist/index.js

Verify Claude Code configuration:

cat ~/.claude/mcp.json

Data Directory Issues

If you encounter permission errors, ensure the data directory exists and is writable:

mkdir -p data/projects data/sessions
chmod -R 755 data/

Claude Code Logs

Check Claude Code logs for connection issues:

# The server logs errors to stderr, which Claude Code captures
# Check your terminal output when starting Claude Code

Privacy and Data

All project data is stored locally on your machine
No data is transmitted to external services
JSON files can be easily backed up or version controlled
Each developer/machine maintains separate project contexts

Contributing

Fork the repository
Create a feature branch
Make your changes
Add tests if applicable
Submit a pull request

License

MIT License - see LICENSE file for details

Support

For issues related to:

MCP Protocol: See Model Context Protocol documentation
Claude Code: See Claude Code documentation
READ THE DOCS: See official TS SDK for MCP
This Server: Open an issue in this repository

This server cannot be installed

security - not tested

license - permissive license

quality - not tested

How are these scores calculated?

A persistent memory layer for Claude Code that maintains project information, technology stack, tasks, decisions, and session history between coding sessions, eliminating the need to re-explain project context.

Related MCP Servers

mcp-knowledge-graph
shaneholloman
A
security
A
license
A
quality
An improved implementation of persistent memory using a local knowledge graph with a customizable --memory-path. This lets Claude remember information about the user across chats.
Last updated -
9
426
512
JavaScript
MIT License
Knowledge Graph Memory Server
modelcontextprotocol
-
security
A
license
-
quality
A basic implementation of persistent memory using a local knowledge graph. This lets Claude remember information about the user across chats.
Last updated -
9
55,084
61,341
TypeScript
MIT License
Claude Server MCP
davidteren
A
security
F
license
A
quality
Provides sophisticated context management for Claude, enabling persistent context across sessions, project-specific organization, and conversation continuity.
Last updated -
4
12
JavaScript
Knowledge Graph Memory Server
AgentWong
-
security
A
license
-
quality
A persistent memory implementation using a local knowledge graph that lets Claude remember information about users across conversations.
Last updated -
6
Python
MIT License

View all related MCP servers

MCP Project Context Server