Routes ChatGPT, Claude, Gemini, and Perplexity sessions or local models into coding clients as one local MCP endpoint for AI queries.
Also known as Zen4-bit/Proxima
- Stars
- 1,210
- Tools
- 41
- Downloads, 30 days
- —
- Latest version
- —
- Last commit
- Oct 16, 2026
- License
- —
What is Proxima MCP?
Proxima routes ChatGPT, Claude, Gemini, and Perplexity sessions or local models into coding clients as one local MCP endpoint for AI queries. It exposes 41 tools, such as list_available_models, ask_chatgpt, ask_claude.
Summary generated from the project's README
About Proxima MCP server
Proxima acts as a centralized local gateway that routes various AI models into coding environments like Cursor, VS Code, Windsurf, or Claude Desktop. It allows developers to access frontier reasoning models by connecting to existing web-based sessions from ChatGPT, Claude, Gemini, and Perplexity without requiring expensive API subscriptions. By using session routing, the server emulates your logged-in browser accounts through sandboxed background views to capture model responses directly.
For those who prefer official integrations, the server provides a Bring Your Own Key mode supporting providers such as OpenAI, Anthropic, DeepSeek, and Groq. It also integrates with local offline engines like Ollama and LM Studio to ensure code privacy. The system includes a self-healing Python agent capable of executing codebase edits, running test suites, and driving browser tasks via the Chrome DevTools Protocol. This setup transforms multiple fragmented AI services into a single, standard local MCP endpoint for all your development queries.
What you can do with it
- 1Access frontier models for freeUse your existing web-based subscriptions for ChatGPT or Claude directly inside your code editor.
- 2Automate codebase debuggingInstruct an agent to find bugs, apply patches, and run tests until the code is functional.
- 3Perform autonomous UI testingHave an agent interact with web frontends to verify layouts and user flows.
Written from the project's README. Every use case is checked against a quote from it.
Proxima MCP tools 41
Detected from the READMElist_available_modelsask_chatgptask_claudeask_geminiask_perplexityask_modelask_all_aissmart_querynew_conversationgenerate_codereview_codeexplain_code
Show all 41 toolsShow fewer tools
optimize_codeverify_codesolvefix_errorexplain_errorconvert_codebuild_architecturewrite_testssecurity_auditdeep_searchddg_searchweb_scrapeget_ui_referencecontentcomparedebateverifyanalyze_filereview_code_filerun_workflowrun_loopcrewproxima_cost_reportproxima_agentic_statusclear_cacheshow_windowhide_windowtoggle_windowset_headless_mode
Automated checks
Ran Nov 12, 2026Full report →Passed our automated checks. That is not a security audit: read the code and give the server the narrowest access it needs. How checks work · What to fix for more points
- Source repository linked and reachablePass
- Open source license (OSI)No licenseFinding
- Commit or release in the last yearPass
- Package name not close to a popular packageNot checked
- Remote endpoint uses HTTPSNot checked
- Destructive tools are labelledPass
- No hidden instructions to the modelPass
- No critical advisory in the package or its dependenciesNot checked
README
View on GitHubProxima
All your AI models, working under one roof.
Run frontier LLMs directly inside Cursor, VS Code, Windsurf, or Claude Desktop using free browser login sessions or local offline providers. Ships with a self-healing Python agent, multi-agent delegation, and cross-session memory.
- Why Proxima?
- Interface Preview
- Routing Modes
- Sponsor Wall
- Meet Proxima Agent
- State, Memory & Prompt Management
- Quick Start
- Architecture
- All MCP Tools (40)
- REST API
- WebSocket
- CLI
- SDKs
- Security & Privacy
- Frequently Asked Questions
- Testing
- Contributing
- License
Why Proxima?
In late 2025, I hit a massive roadblock with AI coding tools. Outdated training data caused coding models to frequently hallucinate, guess wrong solutions, and ruin codebases. I tried setting up local agents using Model Context Protocol (MCP) APIs, but the results were disappointing. The API responses were subpar and inaccurate, all while running up a bill for every single prompt.
That’s when a wild idea struck: What if we could turn actual web-based models—like ChatGPT, Gemini, Claude, and Perplexity—into local MCP servers? By routing queries directly through free, logged-in browser accounts, I could give my local agents access to frontier reasoning models. No expensive API keys required.
Proxima was born as a personal utility. I used it heavily for months to streamline my own work with no plans to open-source it. However, seeing other developers struggle with the same API costs and model hallucinations, I decided to share it. Proxima was created to provide a local, privacy-focused routing engine that connects development tools to active sessions without requiring paid subscriptions or API plans.
- API Subscription Fatigue: Stacking multiple AI subscriptions (ChatGPT Plus, Claude Pro, Perplexity Pro) adds up fast.
- Costly Development Keys: Querying raw API endpoints directly from code editor extensions drains credits quickly on large codebases.
- Local-Model Privacy: When running fully local models via Ollama or LM Studio, your code never leaves your machine — no cloud provider, no data exposure.
- Fragmented Tooling: Constantly switching between browser windows, terminals, and editor panels disrupts your cognitive coding flow.
The Solution: Proxima
Proxima serves as a local development gateway that centralizes and runs all your AI models together on 127.0.0.1. By handling protocol translation and session routing in the background, it enables your coding agents and development clients to interact with multiple advanced providers or offline engines as a single, standard local endpoint.
Interface Preview
Routing Modes
Proxima supports two primary modes to power your editor and agent integrations:
1. Session Routing (Default)
- Free Account Emulation: Routes prompts through your logged-in browser accounts (ChatGPT, Claude, Gemini, Perplexity) inside sandboxed background browser views.
- No API Keys Required: Reuses standard local cookies and browser sessions. No passwords or credentials are saved.
- Renderer-Level Interception: Captures tokens directly from internal WebSocket and API streams, bypassing brittle HTML selectors for faster and more stable routing.
2. BYOK (Bring Your Own Key) Routing
- Broad Model Support: Support for OpenAI, Anthropic, Google, DeepSeek, Groq, xAI, OpenRouter, Together, Fireworks, Mistral, and NVIDIA.
- Local Offline Hardware: Intercepts configurations to run local models via Ollama or LM Studio.
- Secure Storage: Keys are saved locally using your operating system's native keychain vault (via Electron's SafeStorage).
- Local Brain Integration: Automatically applies context compaction, factual recall, and prompt-injection screening.
Sponsor Wall
Proxima keeps evolving thanks to these amazing people
Bloome
💎 Featured Sponsor
Multiple AI agents in one shared chat — not one assistant, but a whole team. Drop in a task and they split the work, hand off, cross-check details, and push back until the output is right. They generate tables, docs and dashboards inline — zero setup, runs in the cloud on web and mobile, and shareable with your team. 👉 Try Bloome
@TheNetworker
⭐ Star Sponsor · 🥇 First Sponsor
Great things are built together — Be a part of our journey →
Meet Proxima Agent
The repository contains proxima-agent/, a local Python assistant. It executes codebase edits, runs test suites, and drives browser tasks by routing LLM calls through Proxima. This allows the agent to run completely free using your website providers or with custom API keys via BYOK mode.
Core Agent Capabilities
- Self-Healing Debugging Loop: Executes code, captures terminal and test-suite errors, and iteratively refactors the codebase until all tests pass.
- Autonomous Browser Control: Drives Chrome instances via Chrome DevTools Protocol (CDP) to interact with frontends, verify UI layouts, and test user flows.
- Dynamic Skill Generation: Writes custom Python helper scripts on the fly, tests them, and packages them into reusable runtime skills (
skills.db) to expand its capabilities. - Symbol-Mapped Codebase Analysis: Maps local files, builds class/function symbol hierarchies, and isolates relevant code blocks to handle large context limits efficiently.
A Real-World Agent Scenario
Imagine you instruct the agent: "Find the bug in my token verification module, patch it, and verify that the authentication tests pass."
Here is the exact trace of how Proxima Agent executes this task:
sequenceDiagram
autonumber
actor User
participant Agent as Proxima Agent
participant Code as Codebase
participant Test as Test Suite
participant Browser as Chrome (CDP)
participant Audit as Reviewer Agent
User->>Agent: "Find the bug in token verification..."
Agent->>Code: 1. Ingest files & build symbol map
Agent->>Test: 2. Run test suite to capture failure trace
Agent->>Code: 3. Synthesize & write code patch
Agent->>Browser: 4. Emulate login & verify user flow
Agent->>Audit: 5. Spawn sub-agent to audit security
Agent->>User: 6. Request approval (present diff & logs)
Gated Execution Safety
The agent is bound by customizable safety permissions:
- Full Auto: Executes all file writes and terminal commands instantly.
- Smart: Auto-approves reading/searching but prompts you before running commands or overwriting code.
- Suggest: Shows proposed code diffs and command lines, waiting for your manual approval.
State, Memory & Prompt Management
To keep workflows fast and context accurate, Proxima features separate prompt and memory systems depending on the active routing engine.
Context Tracking & Prompt Routing
- Session Mode: In this mode, the target provider website (e.g., ChatGPT, Claude) maintains the active conversation state. Sending a massive system prompt containing 40+ tool definitions on every message would bloat the browser's context window, increasing latency and cost. Instead, Proxima runs a fast local classifier every turn. It dynamically analyzes your task and injects only the necessary tool references and relevant self-generated procedural hints.
- BYOK & Local Mode: Proxima's prompt compiler manages the message payload lifecycle for custom API keys and offline endpoints. It formats the conversation history, applies system instructions dynamically, and executes a context compaction loop to summarize older chat turns, preventing token limit errors during large developer prompts.
Local SQLite Memory Engines
Proxima maintains four separate, local, SQLite-backed databases (~/.proxima-agent/*.db) to enable cross-session statefulness:
- Conversation Vault (
vault.db): Tracks session lineage (supporting parent-child structures for multi-agent forks) and stores message histories securely. - Insight Store (
insights.db): Extracts and stores cross-session user preferences, workspace patterns, and environmental facts to prevent repetitive setups. - Experience Learning (
memory.db): Automatically caches compilation errors, syntax exceptions, and the edits that resolved them. The agent queries this history during self-healing loops to apply proven fixes instantly. - Procedural Skills (
skills.db): Caches and evaluates custom script actions generated during tasks. The agent evaluates new skills through a Bayesian priority model, promoting them to "proven" or demoting/deprecating them based on Exponential Moving Average (EMA) success rates.
Quick Start
Follow these steps to configure and connect Proxima to your local environment.
1. Prerequisites
| Platform | Requirements |
|---|---|
| Node.js | Version 18+ (Required to run the main server process) |
| Python | Version 3.10+ (Only required for the Proxima Agent) |
| OS | Windows · macOS · Linux support |
2. Install & Start
# Clone the repository
git clone https://github.com/Zen4-bit/Proxima.git
cd Proxima
# Install dependencies & start
npm install
npm start
💡 Windows Users: You can also download and run the latest
.exeinstaller directly from the Releases page.
Once the desktop app opens:
- Session mode: Log into ChatGPT, Claude, Gemini, or Perplexity in their respective tabs.
- BYOK mode: Click Settings and paste your custom API keys or local host addresses.
3. Connect to Your Editor (MCP)
Add this server configuration block to your editor's MCP configuration settings (for example, in Cursor under Settings -> Features -> MCP):
{
"mcpServers": {
"proxima": {
"command": "node",
"args": [
"C:/absolute/path/to/Proxima/src/mcp/index.js"
]
}
}
}
💡 Tip: You can copy the exact configuration block with your machine's absolute paths directly from the Settings ➔ MCP Configuration tab inside the Proxima desktop app window.
Troubleshooting
Python 3.10+ Environment shows "Error" or "Missing"
Symptoms: The Diagnostics panel shows a red ✗ next to Python 3.10+ Environment even though Python is installed on your system.
Cause: On Windows, the app installs to C:\Program Files\Proxima which is a protected directory. During first-time setup, pip install needs to write temporary files in the source folder and fails with "Access is denied" for standard (non-admin) users.
Versions 5.0.0+ with bundled wheel: This issue is resolved automatically. The installer bundles a pre-built
.whlpackage that installs directly into the virtual environment without writing to the app directory. If you still see this error, make sure you're running the latest build.
Quick Fix (older builds):
- Close Proxima completely.
- Right-click the Proxima app (desktop shortcut or Start menu).
- Select "Run as administrator".
- Wait for the setup to complete — you'll see the Python status turn green ✓.
- Close and reopen normally. Admin mode is only needed once.
macOS / Linux: This is rare on these platforms since app directories are usually user-owned. If it occurs, run the app once with sudo to complete the initial setup.
Python is installed but Proxima can't find it
Make sure Python is on your system PATH:
- Windows: During Python installation, check "Add Python.exe to PATH" at the bottom of the installer. If you missed it, re-run the installer → Modify → check the PATH option.
- macOS / Linux: Run
python3 --versionin a terminal. If not found, install via python.org or your package manager.
Proxima requires Python 3.10 or higher.
Architecture
The system consists of three primary layers: the Proxima Runtime Host, the Model Context Protocol (MCP) Server, and the Local Agent Runtime.
1. System Topology & Data Flow
Below is the complete architectural map showing how protocols, IPC bridges, and providers communicate:
graph TD
subgraph Client Layer [Development Client]
Cursor[Cursor / VS Code / Windsurf]
ClaudeClient[Claude Desktop Client]
end
subgraph MCPServer [MCP Server - Node.js]
MCPIndex[src/mcp/index.js]
ToolHandlers["Modular Tool Handlers<br/>(tools-chat / tools-code / tools-search / tools-content / tools-workflow)"]
end
subgraph CoreEngine [Proxima Core Process - Electron]
HTTPServer["HTTP Server :3210<br/>(OpenAI REST & WS)"]
MessageBus["handleMCPRequest()<br/>(Central Message Bus)"]
PythonAgent["Local Agent Runtime<br/>(python-env)"]
end
subgraph RoutingEngines [Routing Engines]
SessionMode["Session Mode<br/>(Browser Manager & background BrowserViews)"]
BYOKMode["BYOK Mode<br/>(BYOK Router & Context Pipeline)"]
end
subgraph Providers [AI Providers]
WebSessions["Active Web Sessions<br/>(ChatGPT / Claude / Gemini / Perplexity)"]
OfficialAPIs["Official LLM APIs<br/>(OpenAI / Anthropic / Groq / etc.)"]
end
%% Communications
Cursor -->|StdIO JSON-RPC| MCPIndex
ClaudeClient -->|StdIO JSON-RPC| MCPIndex
MCPIndex --> ToolHandlers
ToolHandlers -->|IPC TCP:19222| MessageBus
HTTPServer --> MessageBus
PythonAgent --> MessageBus
MessageBus --> SessionMode
MessageBus --> BYOKMode
SessionMode -->|Session Compliance| WebSessions
BYOKMode -->|Dynamic Fallback / Decryption| OfficialAPIs
2. Core Subsystems
Browser Session Compliance Layer
For Session Mode, Proxima loads each provider inside isolated BrowserView containers. The compliance layer includes:
- User-Agent Management: Maintains standard browser user-agent strings for compatibility.
- Page Context Configuration: Sets up standard preload scripts for correct rendering and provider compatibility.
- Direct Response Streaming: Engine scripts (
electron/providers/engines/*) capture streaming tokens directly from provider HTTP responses for real-time output.
Worker Control Protocol (WCP)
The Agent's workflow engine uses an internal command protocol (WCP) for multi-step task delegation, research routing, and temporary state management across sub-agents. See docs/architecture.md for protocol details.
BYOK Local Brain & Context Pipeline
When BYOK Mode is active, Proxima utilizes a local intelligence buffer:
- Factual Recall & Experience Log: Stores previous code errors, terminal exceptions, and successful fixes in an encrypted SQLite database to avoid repeating programming mistakes.
- Context Compaction Pipeline: Uses token-estimation and cheap pruning heuristics (
byok/context/) to summarize long conversation loops when approaching provider limits (preventing out-of-context crashes). - Ollama/LM Studio Bridge: Intercepts unknown custom provider configurations and loops them through standard OpenAI-compatible endpoints to support offline, local hardware execution.
Read docs/architecture.md for structural diagrams and docs/MIGRATION-v5.0-to-v5.5.md for v5.0.0 → v5.5.0 upgrade notes.
All MCP Tools (41)
Registered by the modular MCP server (src/mcp/). Proxima also provides dynamic model inspection via the proxima://models MCP resource.
Core Orchestration Tools
The following signature capabilities represent Proxima's custom orchestration logic:
| Tool | Command | Description |
|---|---|---|
| Multi-Agent Collaboration | crew |
Spawn a collaborative swarm of models to review, critique, and optimize code before returning it. |
| Consensus Routing | smart_query |
Query multiple model providers simultaneously, cross-verify their answers, or make them debate. |
| Codebase Intelligence | analyze_file |
Ingest local files, build structural symbol maps, and scan/strip credentials or secrets. |
| Multi-Source Research | deep_search |
Perform targeted searches across Web, Reddit, GitHub, News, Academic, and Fact-check engines. |
| Cross-AI Fact-Checking | verify |
Compare output from different providers, highlight inconsistencies, and score confidence. |
| Algorithmic Compilation | solve |
Loop with compiler output and test runners to self-correct code based on diagnostic output until compilation passes. |
| Vulnerability Scanner | security_audit |
Scan code snippets for SQL injections, XSS, insecure storage, and deprecated dependencies. |
| Complex Workflow Loops | run_workflow |
Chaperone multi-step tasks requiring chaining and conditional validation of different tools. |
Proxima MCP questions
What tools does Proxima MCP provide?
It exposes 41 tools, including list_available_models, ask_chatgpt, ask_claude, ask_gemini, ask_perplexity.
Does Proxima require API keys?
No. By default it routes prompts through your logged-in browser sessions, and BYOK is optional for production use.
Which AI providers can Proxima connect to?
It works with ChatGPT, Claude, Gemini, and Perplexity sessions, plus BYOK providers like OpenAI, Anthropic, Google, DeepSeek, Groq, and local Ollama or LM Studio models.
Where does Proxima run?
It runs locally as a gateway on 127.0.0.1, so your code stays on your machine.
What coding tools can I use Proxima with?
You can connect it to Cursor, VS Code, Windsurf, or Claude Desktop as a local MCP server.
How are BYOK API keys stored?
Keys are saved locally in your operating system's native keychain vault.