Claude Context Local

claude-context-local

> Project Philosophy: This project maintains the full history of the original claude-context for transparency and attribution, but represents a divergent branch focused on privacy and local operation. While the original continues toward cloud integration, we're committed to a 100% local, privacy-first approach. Both projects serve different needs in the ecosystem.

A local-first implementation of claude-context MCP server that replaces cloud dependencies with local alternatives for complete privacy and zero API costs.

🚀 Key Features

• 100% Local: No external API calls, all processing happens on your machine
• PostgreSQL + pgvector: Replaces Milvus/Zilliz Cloud with local PostgreSQL
• Ollama Embeddings: Uses free, open-source models instead of OpenAI
• Privacy-First: Your code never leaves your machine
• Zero API Costs: No subscription fees or usage charges
• Multimodal Support: Nomic embedding model supports text and images

⚡ Quick Start

Prerequisites

1. Install PostgreSQL and pgvector:

brew install postgresql@14 pgvector
brew services start postgresql@14

1. Install and configure Ollama:

brew install ollama
ollama serve  # Start in a separate terminal
ollama pull DC1LEX/nomic-embed-text-v1.5-multimodal

1. Setup database:

psql -U postgres -c "CREATE DATABASE embeddings;"
psql -U postgres -d embeddings -c "CREATE EXTENSION IF NOT EXISTS vector;"

Installation

# Clone the repository
git clone https://github.com/MikeO-AI/claude-context-local.git
cd claude-context-local

# Install dependencies
pnpm install

# Build the project
pnpm build

# Test the integration
node test-postgres.js

Running the MCP Server

Method 1: Direct Installation (Recommended)

# First, validate your setup
node validate-mcp-setup.js

# Start with default settings (PostgreSQL on localhost, Ollama on localhost:11434)
node packages/mcp/dist/index-postgres.js

# Or with custom configuration
POSTGRES_HOST=your-db POSTGRES_PASSWORD=your-pass node packages/mcp/dist/index-postgres.js

Method 2: NPM Package

Install globally from npm:

npm install -g @mikeo-ai/claude-context-local-mcp
claude-context-local-mcp

# Or use with npx (recommended)
npx @mikeo-ai/claude-context-local-mcp@latest

Method 3: Claude MCP Add Command

claude mcp add claude-context-local \
  -e EMBEDDING_PROVIDER=Ollama \
  -e POSTGRES_DATABASE=embeddings \
  -- npx @mikeo-ai/claude-context-local-mcp@latest

For detailed setup instructions, see [MCP-SETUP-GUIDE.md](./MCP-SETUP-GUIDE.md)

⚙️ Configuration

Claude Code Integration

Add to your Claude Code config (~/Library/Application Support/Claude/claude_desktop_config.json):

{
  "mcpServers": {
    "claude-context-local": {
      "command": "node",
      "args": ["/absolute/path/to/claude-context-local/packages/mcp/dist/index-postgres.js"],
      "env": {
        "EMBEDDING_PROVIDER": "Ollama",
        "OLLAMA_MODEL": "DC1LEX/nomic-embed-text-v1.5-multimodal",
        "OLLAMA_HOST": "http://localhost:11434",
        "POSTGRES_HOST": "localhost",
        "POSTGRES_PORT": "5432",
        "POSTGRES_DATABASE": "embeddings",
        "POSTGRES_USER": "postgres",
        "POSTGRES_PASSWORD": "postgres"
      }
    }
  }
}

Environment Variables

| Variable | Default | Description | |----------|---------|-------------| | EMBEDDING_PROVIDER | Ollama | Embedding provider (Ollama recommended) | | OLLAMA_MODEL | DC1LEX/nomic-embed-text-v1.5-multimodal | Ollama model to use | | OLLAMA_HOST | http://localhost:11434 | Ollama server URL | | POSTGRES_HOST | localhost | PostgreSQL host | | POSTGRES_PORT | 5432 | PostgreSQL port | | POSTGRES_DATABASE | embeddings | Database name | | POSTGRES_USER | postgres | Database user | | POSTGRES_PASSWORD | postgres | Database password |

🐳 Docker Setup (Optional)

For easier deployment, use Docker Compose:

# docker-compose.yml
version: '3.8'
services:
  postgres:
    image: pgvector/pgvector:pg16
    environment:
      POSTGRES_DB: embeddings
      POSTGRES_USER: postgres
      POSTGRES_PASSWORD: postgres
    ports:
      - "5432:5432"
    volumes:
      - postgres_data:/var/lib/postgresql/data

  ollama:
    image: ollama/ollama
    ports:
      - "11434:11434"
    volumes:
      - ollama_data:/root/.ollama
    command: serve

volumes:
  postgres_data:
  ollama_data:

Then:

docker-compose up -d
docker exec -it claude-context-local_ollama_1 ollama pull DC1LEX/nomic-embed-text-v1.5-multimodal

🔧 MCP Tools

add_codebase

Index a codebase directory for semantic search:

add_codebase({
  path: "/path/to/your/project"
})

search_codebase

Search through indexed codebases:

search_codebase({
  query: "authentication logic",
  path: "/path/to/your/project",
  limit: 10
})

📊 Comparison with Original

| Feature | Original (Milvus) | Local (PostgreSQL) | |---------|-------------------|--------------------| | Vector Database | Milvus/Zilliz Cloud | PostgreSQL + pgvector | | Embeddings | OpenAI/VoyageAI | Ollama (local) | | Privacy | Data sent to cloud | 100% local | | Cost | API usage fees | Free | | Setup | Cloud account required | Local installation | | Internet | Required | Not required | | Dimensions | Variable | 768 (configurable) |

🙏 Credits & Attribution

This project is based on claude-context by Zilliz, licensed under the MIT License.

What's Changed

• Replaced Milvus/Zilliz Cloud with PostgreSQL + pgvector
• Replaced OpenAI embeddings with Ollama
• Added multimodal embedding support
• Removed all external API dependencies
• Added comprehensive PostgreSQL implementation

Original Contributors

• Zilliz Team - Original claude-context implementation
• Cheney Zhang - Original author

📚 Documentation

• [PostgreSQL Setup Guide](./README-POSTGRES.md) - Detailed PostgreSQL configuration
• [Test Script](./test-postgres.js) - Verify your installation
• Original Documentation - Reference the original project

🔍 Troubleshooting

Common Issues

1. pgvector not found

``bash brew install pgvector psql -U postgres -d embeddings -c "CREATE EXTENSION vector;" ``

1. Ollama connection failed

``bash ollama serve # Start Ollama service ``

1. Model not found

``bash ollama pull DC1LEX/nomic-embed-text-v1.5-multimodal ``

🗺️ Roadmap

• [ ] SQLite support for simpler setup
• [ ] Additional Ollama model support
• [ ] Web UI for codebase management
• [ ] Incremental indexing
• [ ] Docker one-click deployment
• [ ] Support for more local embedding models

🤝 Contributing

Contributions are welcome! This is a community project aimed at providing a fully local alternative to cloud-based code context solutions.

How to Contribute

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Submit a pull request

Areas for Contribution

• Support for additional databases (SQLite, DuckDB)
• More embedding model integrations
• Performance optimizations
• Documentation improvements
• Testing and bug fixes

📄 License

MIT License - see [LICENSE](./LICENSE) for details.

This project includes code from claude-context by Zilliz, also licensed under MIT.

⭐ Star History

If you find this project useful, please consider giving it a star!

---

Built with ❤️ for the community by MikeO-AI

Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: MikeO-AI
• Source: MikeO-AI/claude-context-local
• License: MIT

Install and usage instructions live in the source repository linked above.