venira-mcp

Fast, workspace-scoped MCP server for coding agents (OpenCode, Claude Desktop, any MCP client). Two tool modes — Default (29 coding tools + shell, no CI/CD) · Expert (42 tools: default + CI/CD). Setting VENIRA_JS_EXEC_MODE=ask, semi-auto or auto adds project_execute_js (30 / 43). Pure Node, 1 native dependency (better-sqlite3), no GUI, no external binary.

Security scope. Venira is a guard rail with an audit trail, not a sandbox. It runs with the privileges of the OS user that started it. The workspace lock limits the paths the file tools can touch (unless VENIRA_UNRESTRICTED=1), not what a shell command does: commands are classified by rules (allow / ask / deny) and every call is audited, but a malicious prompt can still steer the agent into running a harmful command that the active profile lets through (with off, every command runs). Anything running as the same OS user can read the keys in VENIRA_DATA_DIR. For untrusted workspaces, or whenever you need a real isolation boundary, run Venira in a container or VM. Details: SECURITY.md.

1. Setup

One-line install (run in your project, then restart the client):

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

Prefer your agent? Paste this prompt into OpenCode/Claude/Cursor:

Set up Venira MCP for this workspace.
1. Detect my MCP client config path.
2. Run: npx --yes venira-mcp@latest --install auto --workspace .
3. Restart the client. Then call project_health to verify.

Manual config (pick your client):

All use the same npx command. See §2 for ready-to-copy JSON/TOML.

In this repo .vscode/mcp.json is git-ignored because it holds machine-specific settings (and may relax security flags). Copy .vscode/mcp.example.json to .vscode/mcp.json and adjust it locally.

2. Client configs (copy-paste)

The examples use four environment variables: workspace, tool set, output size, and security posture. For most users, change only VENIRA_WORKSPACE and keep VENIRA_SECURITY_PROFILE=balanced.

OpenCode / VS Code / Cursor / Claude / Kimi / DeepSeek / Antigravity — use the wrapper format supported by your client:

// OpenCode: "mcp" > "venira" > "environment"
{
  "mcp": {
    "venira": {
      "type": "local",
      "command": ["npx", "--yes", "--package=venira-mcp@latest", "venira-mcp"],
      "enabled": true,
      "environment": {
        "VENIRA_WORKSPACE": "/absolute/path/to/project",
        "VENIRA_TOOL_MODE": "expert",
        "VENIRA_OUTPUT_MODE": "full",
        "VENIRA_SECURITY_PROFILE": "balanced",
        // Small model / restricted context? Uncomment to slim tools/list:
        // "VENIRA_PROFILE": "core"
      }
    }
  }
}

// VS Code: "servers" > "venira" > "env"; ${workspaceFolder} expands automatically.
{
  "servers": {
    "venira": {
      "type": "stdio",
      "command": "npx",
      "args": ["--yes", "--package=venira-mcp@latest", "venira-mcp"],
      "env": {
        "VENIRA_WORKSPACE": "${workspaceFolder}",
        "VENIRA_TOOL_MODE": "expert",
        "VENIRA_OUTPUT_MODE": "full",
        "VENIRA_SECURITY_PROFILE": "balanced"
      }
    }
  }
}

// Claude / Cursor and compatible clients: "mcpServers" > "venira" > "env"
{
  "mcpServers": {
    "venira": {
      "command": "npx",
      "args": ["--yes", "--package=venira-mcp@latest", "venira-mcp"],
      "env": {
        "VENIRA_WORKSPACE": "/absolute/path/to/project",
        "VENIRA_TOOL_MODE": "expert",
        "VENIRA_OUTPUT_MODE": "full",
        "VENIRA_SECURITY_PROFILE": "balanced"
      }
    }
  }
}

Generic MCP JSON example

For clients that accept the common mcpServers JSO

... View full README on GitHub