# venira-mcp [Health: Active]

**Category:** 🤖 Coding Agents  
**Repository:** https://github.com/N0moreher0/Venira-mcp  
**GitHub Stars:** 0  
**npm Downloads (last month):** 7501  
**Views:** 0  
**Installs:** 0  
**Upvotes:** 0  
**Directory Page:** https://allmcps.com/mcp/venira-mcp

## Description
venira-mcp — a standalone Model Context Protocol (MCP) server that gives coding agents (OpenCode, Claude Desktop, any MCP client) 44 workspace-scoped tools: file read/write/edit/delete, batch reads, line-range reads, content search, recent files, code int

## Tools
Capabilities this server exposes over MCP:

- **project_list_files** — List files and directories (depth 1-3, limit up to 200). include_ignored=1 also lists ignored folders.
Use when: you need the directory tree or want to confirm a path exists.
Avoid when: you know the file (project_read_file) or want what changed lately (project_recent_files).
Output: entries[] {relative_path, kind, size_bytes}, truncated.
- **project_read_file** — Read a text file, whole or by line range (start_line/end_line, 1-based; ranges[] for several disjoint ranges of one file).
Use when: you need one file's content. When truncated, call again with start_line=next_start_line.
Avoid when: you need 2+ files (project_read_batch) or only size/mtime (project_get_file_info).
Output: text, first_line, last_line, total_bytes, truncated, next_start_line (when truncated). Missing path gives not_found.
- **project_get_file_info** — Return kind, size and modification time of a path.
Use when: you need to know whether a path exists or how big it is.
Avoid when: you need the content (project_read_file).
Output: kind, size_bytes, modified_unix_seconds. Missing path gives not_found.
- **project_search** — Search by kind: file_name, directory_name, literal_content (regex=1 for regex) or definition (symbol declaration lines).
Use when: you must locate code, strings or symbols before reading. hybrid=1 tags each hit with source and confidence.
Avoid when: you know the path (project_read_file), want one file's structure (project_outline_symbol), a symbol's usages (project_symbol_references) or files ranked by several keywords (project_selective_search).
Output: hits[] {relative_path, line_number, snippet}, complete, total_match_lines, files_matched. No match is ok with empty hits.
- **project_recent_files** — List recently modified files, newest first, plus session_edits (files you wrote in this session).
Use when: you start or resume a task, or finished a build, format or git step and want to see what changed. Feed the top paths into project_read_batch.
Avoid when: you need the full tree (project_list_files) or a content search (project_search).
Output: entries[] {relative_path, size_bytes, modified_ago_seconds}, session_edits, truncated.
- **project_read_batch** — Run up to 8 read-only ops in one call. operation is the short name (list_files|read_file|get_file_info|search) mapping to project_list_files|project_read_file|project_get_file_info|project_search; arguments hold exactly that tool's parameters.
Use when: you need 2+ reads or mixed read steps. Items run in order and one failing item does not stop the rest.
Avoid when: a single read (project_read_file) or any edit (project_edit_batch).
Output: responses[] each {ok, response | error}, total_bytes_returned.
- **project_write_file** — Write a file. mode=create (fails if it exists), overwrite, or append. create_dirs=1 creates parent folders.
Use when: you create a file, replace one entirely, or append. expected_sha256 refuses the write if the file changed since you read it.
Avoid when: you change a few lines (project_edit_file). overwrite is immediate and not undoable: project_snapshot first when the file is not in git.
Output: action (created|overwritten|appended), bytes_written, sha256_after. mode=create on an existing path gives conflict.
- **project_edit_file** — Replace exact text: old_text to new_text, or edits[] for several replacements in one file (edits[] wins).
Use when: you make a targeted change. old_text must match exactly once; replace_all=1 replaces every match. pass expected_sha256 to refuse stale content and get a verified re-read.
Avoid when: you rewrite the whole file (project_write_file) or change several files at once (project_edit_batch).
Output: replacements, sha256_before, sha256_after, verified (when expected_sha256 is given). Failures: old_text_not_found, old_text_ambiguous (returns each match with line context).
- **project_edit_batch** — Apply edits across one or more files all-or-nothing. Each item takes edit_file arguments (relative_path, old_text, new_text, ...). The first failure rolls back every touched file from an automatic snapshot and skips the rest.
Use when: a change spans several files or sections and must land completely or not at all.
Avoid when: you make one edit (project_edit_file).
Output: success: per-edit {relative_path, replacements, sha256_after}. Failure: ok=false, error batch_failed, data {executed, skipped, rollback_succeeded, snapshot_id}.
- **project_delete_path** — Delete a file or directory (recursive=1 is required for directories). Not undoable.
Use when: you remove files or folders. Take a project_snapshot first when they are not in git.
Avoid when: the target is uncertain (check with project_get_file_info or project_list_files).
Output: entries_deleted, bytes_deleted. Missing path gives not_found.
- **project_shell_run** — Run a shell command in the workspace (shell: powershell|cmd|bash, relative_cwd, timeout_ms). Default is background: returns run_id, poll project_shell_status. background=0 blocks until exit and returns stdout/stderr.
Use when: you build, test, run git or install packages. Use background=0 for short commands whose output you need now.
Avoid when: you read or edit files (file tools) or run a tiny JS calculation (project_execute_js).
Output: run_id, kill_key, running, exit_code, timed_out, stdout/stderr (background=0) or stdout_tail/stderr_tail. ok=true only means it ran: read command_status/exit_code. approval_required: ask the user to approve, then retry once with approval_id.
- **project_shell_status** — Return the state and output tail of a shell run. wait_seconds (0-30) waits up to that long for it to finish.
Use when: after a background project_shell_run: poll until running=false, then read exit_code.
Avoid when: you have no run_id yet.
Output: running, exit_code, stdout_tail, stderr_tail. Unknown run_id gives not_found (run ids only live for this session).
- **project_shell_cancel** — Kill a running command and its child processes. Needs run_id and kill_key from project_shell_run.
Use when: a command hangs or its result is no longer needed.
Avoid when: the run already finished (project_shell_status).
Output: accepted, cleanup_complete.
- **project_create** — Create a directory; missing parents are created unless create_dirs=0.
Use when: you need an empty directory. For a file use project_write_file, which also creates parent folders.
Avoid when: you write file content (project_write_file) or edit existing content (project_edit_file).
Output: directory_created {relative_path, created, parents_created}.
- **project_health** — Server diagnostics: version, workspace, security posture and warnings, caches, queue, running shells, latency, snapshot store, audit status.
Use when: you debug slowness or errors, or want the security warnings before risky work. include_audit=0 skips the audit query.
Avoid when: normal file work.
Output: server, corehost, queue, caches, shells, posture {level, findings}, snapshots, metrics.
- **project_cache_clear** — Clear in-process caches (all, read, info, list, search, recent, negative, graph, shell).
Use when: reads look stale because a tool changed files outside Venira.
Avoid when: normal flow: writes already invalidate caches.
Output: cleared entry counts per cache.
- **project_trace_status** — Show recent traced tool calls and the trace configuration (needs VENIRA_TRACE=1).
Use when: you want to see what ran recently without opening the log file.
Avoid when: tracing is off (the buffer is empty).
Output: enabled, file, buffered, recent[] (newest last).
- **project_read_audit** — Read recent audit-log rows, newest first. Filter by session_id, operation, outcome, since_unix; verify=1 checks the hash chain.
Use when: you review what was done and why (the reason field), in this or an earlier session.
Avoid when: you want live metrics (project_health).
Output: rows[], count, truncated, chain_ok (verify=1).
- **project_shell_cancel_session** — Kill every shell run started in this session.
Use when: you tear down a stuck session with several running commands.
Avoid when: only one run must stop (project_shell_cancel).
Output: cancelled_run_ids[], count.
- **project_outline_symbol** — List a source file's top-level symbols (functions, classes, types, interfaces) with line numbers.
Use when: you want a file's structure before reading or refactoring it.
Avoid when: you need usages (project_symbol_references), a text search (project_search) or the text itself (project_read_file).
Output: total_symbols, symbols[] {name, kind, line, signature}.
- **project_diff_files** — Unified diff between two workspace files.
Use when: you compare two versions of a file, such as a backup and the current one.
Avoid when: binary files, or git history (run git with project_shell_run).
Output: lines_added, lines_removed, unified_diff, truncated.
- **project_symbol_references** — Find occurrences of a symbol name. scope=file needs relative_path (one file); scope=workspace (default) searches all files. limit caps the workspace scan, max_references caps the returned list.
Use when: you check where a symbol is used before renaming or changing it.
Avoid when: you only need its declaration (project_outline_symbol) or arbitrary text (project_search).
Output: count, references[] {relative_path, line_number, context}.
- **project_selective_search** — Rank files by how well they match several patterns (must, weight, fuzzy score) within files_hint or a shallow listing.
Use when: you must find the right module among candidates using several keywords.
Avoid when: you search for one literal (project_search) or do not know where to start (project_plan_read_batch).
Output: hits[] {relative_path, line_number, text, score, matched}, total_files, total_hits.
- **project_dependency_graph** — Build the import and reference graph for TypeScript/JavaScript, Python, Rust, Go, Java and Kotlin. format: json, dot or mermaid.
Use when: you want module structure or what a subtree depends on. Narrow with relative_path, depth, languages.
Avoid when: you need usages of one symbol (project_symbol_references) or the impact of an edit (project_change_impact).
Output: nodes[], edges[] {from, to, type, confidence}, external[], unresolved[], stats, truncated. dot and mermaid return data.graph.
- **project_change_impact** — List the files and symbols affected by changing given files or symbols (direction: dependents, dependencies or both). At least one of files/symbols; a symbol seed takes {name, relative_path} (file is an alias).
Use when: you are about to rename or change something and need which files to read and which tests to run.
Avoid when: you want the whole graph (project_dependency_graph).
Output: affected[] {id, distance, path, confidence}, summary {affected_files, affected_symbols, tests_affected}, unresolved[].
- **project_detect_harnesses** — Find MCP client configs on this machine (OpenCode, Claude Desktop, Cursor, Codex, Kimi, DeepSeek, Antigravity).
Use when: before project_install_self, to see which configs exist.
Avoid when: you already know the config path.
Output: harnesses[] {harness, detected, config_path, format, note}.
- **project_install_self** — Add the Venira MCP server entry to a client's config. Atomic write with a backup at <file>.venira-bak. dry_run=1 previews.
Use when: the user asks to install Venira into a client.
Avoid when: the config path is unknown (project_detect_harnesses first).
Output: harness, config_path, status (installed|already_present|config_missing|error), needs_restart.
- **project_explain_error** — Match an error or log tail against known failure signatures (TypeScript, Python, git, npm, GitHub, Venira codes) and return the likely cause, fixes and ready next_actions. Offline rules, no model call.
Use when: a command, build or provider call failed and the cause is unclear. Pass error_text or log_tail.
Avoid when: you already know the cause.
Output: matched, summary, diagnoses[] {title, likely_cause, suggested_fix[], next_actions[]}.
- **project_plan_read_batch** — Turn a task description into ranked candidate files and a ready-to-run project_read_batch call (keyword search plus recent files; deterministic, returns no file contents).
Use when: you start in an unfamiliar area: run steps[0] instead of guessing files.
Avoid when: you know the files (project_read_batch) or only need one string or name (project_search).
Output: keywords[], candidates[] {relative_path, reason, hits}, steps[] {tool, arguments, why}.
- **project_snapshot** — Checkpoint and roll back workspace files. action: create (label, paths) | list | restore (id) | delete (id) | mirror (copy to VENIRA_SNAPSHOT_MIRROR_DIR).
Use when: before multi-file refactors or overwriting/deleting files git does not hold. Keep paths narrow and check file_count and skipped. Roll back with restore dry_run=1, then restore with verify=1.
Avoid when: tiny single-file edits or states git already holds.
Output: create: id, file_count, total_bytes, truncated, skipped[]. restore: restored[], deleted_count, skipped[].
- **project_github_connect** — Connect GitHub with Device Flow. action=start returns verification_uri and user_code: show them to the user, then action=poll with pending_id after they authorize. Tokens go to the encrypted vault and are never returned.
Use when: the user wants to connect or replace the GitHub credential without pasting a token.
Avoid when: you only need public read access, or a token is already configured.
Output: start: verification_uri, user_code, pending_id, expiry. poll: pending | denied | expired | connected.
- **project_secret** — Store and inspect tokens without exposing them (AES-256-GCM at rest). action: set | get (metadata only) | list | delete. Inject into commands with project_shell_run secret_env=[NAME]; the GitHub tools read GITHUB_TOKEN on their own.
Use when: you save a non-GitHub token, check expiry or rotation, or remove one. Prefer value_env over value so the secret never appears in chat.
Avoid when: the value is plain config (use .env or the config file). reveal=1 prints plaintext and needs VENIRA_SECRET_ALLOW_REVEAL=1.
Output: set: name, length, expires_at, days_left. get and list: metadata only.

## Claude Desktop Quick Installation
Install path detected from listing signals. Uses `npx` (confidence: high):

```json
"mcpServers": {
  "venira-mcp": {
    "command": "npx",
    "args": ["--yes","--package=venira-mcp@latest","venira-mcp"],
    "env": {
      "VENIRA_WORKSPACE": ""
    }
  }
}
```

**Requires environment variables:** `VENIRA_WORKSPACE` — the values above are empty placeholders; fill in real credentials before running (see the repository for what each one is for).

## Documentation

## What venira-mcp MCP server does

venira-mcp exposes project-management and coding tools to MCP-compatible agents. Its workspace-scoped file tools can read, write, edit, delete, and inspect files; read multiple files in one call; retrieve line ranges; search file contents; and identify recently used files. The available coding tools also include project health checks and code-intelligence operations.

Tool availability depends on the selected mode. Default mode provides 32 coding tools plus shell access and excludes CI/CD operations. Expert mode expands the set to 43 tools by adding CI/CD capabilities. Enabling JavaScript execution adds `project_execute_js`, producing 33 tools in default mode or 44 in expert mode.

## How it works

The server runs as a local Node process, commonly started through `npx --yes venira-mcp@latest`. MCP clients connect to it over their local stdio server configuration. The workspace path is supplied through `VENIRA_WORKSPACE`, and the file tools use that path as their scope unless restrictions are explicitly disabled.

Shell commands are evaluated under a configurable policy. Rules can allow, request approval for, or deny commands, and calls are audited. The security profile controls the default shell behavior: `strict` favors read-only and workspace-local operations, `balanced` is the general-purpose default, `trusted` is more permissive, and `off` disables shell checks with a warning.

JavaScript execution is independently controlled. The `ask` mode requires approval for each call, `semi-auto` keeps containment while removing per-call approval, and `auto` removes that containment as well.

## Setup and configuration

Install it from a project directory with:

```bash
npx --yes venira-mcp@latest --install auto --workspace .
```

After installation, restart the MCP client and call `project_health` to verify the connection. Manual configurations are documented for VS Code, OpenCode, Claude Desktop, Cursor, and Codex. These configurations use the same npx command and set the workspace, tool mode, output mode, and security profile.

The main settings are `VENIRA_WORKSPACE`, `VENIRA_TOOL_MODE`, `VENIRA_OUTPUT_MODE`, and `VENIRA_SECURITY_PROFILE`. `VENIRA_DATA_DIR` can place Venira's local data in a chosen writable directory. `VENIRA_SHELL_MODE` overrides the shell policy selected by the security profile, while `VENIRA_UNRESTRICTED=1` removes workspace path restrictions and should not be used in production.

## Tools and capabilities

- Read, write, edit, delete, and inspect workspace files.
- Read batches of files or selected line ranges.
- Search project content and retrieve recent files.
- Run shell commands under configurable approval rules.
- Use project health and code-intelligence tools.
- Add CI/CD operations in expert mode.
- Optionally execute project JavaScript with selectable approval and containment.
- Audit tool calls and shell activity.

## Limitations and notes

Venira provides guard rails and an audit trail, not a sandbox. It runs with the privileges of the operating-system user that starts it. Workspace restrictions apply to file tools, but shell commands are governed separately and may still cause harmful effects if the active policy permits them.

JavaScript execution in `auto` mode has full network and filesystem access and inherits the environment. Anything running as the same OS user may also read keys stored in `VENIRA_DATA_DIR`. For untrusted workspaces or situations requiring a genuine isolation boundary, run the server inside a container or virtual machine.

_Full upstream README: https://allmcps.com/mcp/venira-mcp/readme_