mcp-auditor

MCP Auditor - Server Mode

npm version npm downloads License: MIT

Run MCP Auditor as a standalone MCP server that can be connected to by Claude Desktop or other MCP clients.

Quick Start

1. Install

Global installation (recommended for server mode):

npm install -g mcp-auditor

From source:

git clone https://github.com/algovate/mcp-auditor.git
cd mcp-auditor
npm install
npm run build

2. Start the server

export MCP_WRAPPED_SERVER_COMMAND=npx
export MCP_WRAPPED_SERVER_ARGS="-y,@modelcontextprotocol/server-filesystem,/tmp"
export MCP_LOG_FILE=./logs/mcp-server.log

mcp-auditor
# or
mcp-auditor-server

Option B: Using a configuration file

export MCP_CONFIG_FILE=./config.json
mcp-auditor

Option C: From source

export MCP_WRAPPED_SERVER_COMMAND=npx
export MCP_WRAPPED_SERVER_ARGS="-y,@modelcontextprotocol/server-filesystem,/tmp"
export MCP_LOG_FILE=./logs/mcp-server.log

npm start

Configuration

Environment Variables

Variable Description Required Default
MCP_CONFIG_FILE Path to JSON config file No -
MCP_SERVER_NAME Name of the server No mcp-auditor-server
MCP_SERVER_VERSION Version of the server No 1.0.0
MCP_WRAPPED_SERVER_COMMAND Command to run wrapped server Yes* -
MCP_WRAPPED_SERVER_ARGS Comma-separated args No -
MCP_WRAPPED_ENV_* Environment vars for wrapped server No -
MCP_LOG_FILE Path to log file No ./logs/mcp-server.log
MCP_LOG_TOOL_CALLS Log tool calls No true
MCP_LOG_TOOL_RESULTS Log tool results No true
MCP_LOG_APPEND Append to log file No true
MCP_LOG_FORMAT Log format (structured/jsonrpc) No structured

* Required unless using MCP_CONFIG_FILE

Configuration File Format

Create a config.json file:

{
  "name": "my-mcp-wrapper-server",
  "version": "1.0.0",
  "wrappedServer": {
    "serverCommand": "npx",
    "serverArgs": ["-y", "@modelcontextprotocol/server-filesystem", "/tmp"],
    "serverEnv": {
      "DEBUG": "false"
    },
    "logFilePath": "./logs/mcp-server.log",
    "logToolCalls": true,
    "logToolResults": true,
    "logAppend": true,
    "logFormat": "structured"
  }
}

See config.example.json for a complete example.

Usage with MCP Clients

Claude Desktop

Add to your Claude Desktop configuration (~/Library/Application Support/Claude/claude_desktop_config.json on macOS):

{
  "mcpServers": {
    "wrapped-filesystem": {
      "command": "node",
      "args": ["/path/to/mcp-auditor/dist/server.js"],
      "env": {
        "MCP_WRAPPED_SERVER_COMMAND": "npx",
        "MCP_WRAPPED_SERVER_ARGS": "-y,@modelcontextprotocol/server-filesystem,/Users/yourname/Documents",
        "MCP_LOG_FILE": "/Users/yourname/logs/mcp-wrapper.log"
      }
    }
  }
}

Or using a config file:

{
  "mcpServers": {
    "wrapped-filesystem": {
      "command": "node",
      "args": ["/path/to/mcp-auditor/dist/server.js"],
      "env": {
        "MCP_CONFIG_FILE": "/path/to/your/config.json"
      }
    }
  }
}

Direct stdio Communication

You can communicate with the server directly via stdin/stdout:

# Start the server
npm run dev:server

# Send JSON-RPC requests via stdin
# Example: List tools
{"jsonrpc":"2.0","id":1,"method":"tools/list","params":{}}

# Call a tool
{"jsonrpc":"2.0","id":2,"method":"tools/call","params":{"name":"read_file","arguments":{"path":"/tmp/test.txt"}}}

Development

Run in development mode

# With environment variables
export MCP_WRAPPED_SERVER_COMMAND=npx
export MCP_WRAPPED_SERVER_ARGS="-y,@modelcontextprotocol/server-filesystem,/tmp"
npm run dev:server

# With config file
export MCP_CONFIG_FILE=./config.example.json
npm run dev:server

Testing the server

Use the MCP Inspector tool to test your server:

npx @modelcontextprotocol/inspector node dist/server/server.js

Set environment variables in the inspector UI or create a config file.

Features

✅ Stdio Transport

The server uses stdio transport, making it compatible with:

✅ Complete MCP Capability Proxying

All capabilities from the wrapped server are exposed:

✅ Comprehensive Logging

All I/O operations are logged to the specified file:

Log Formats:

✅ Flexible Configuration

Configure via:

Examples

Example 1: Wrap Filesystem Server

export MCP_WRAPPED_SERVER_COMMAND=npx
export MCP_WRAPPED_SERVER_ARGS="-y,@modelcontextprotocol/server-filesystem,/Users/yourname/Documents"
export MCP_LOG_FILE=./logs/filesystem.log
npm start

Example 2: Wrap Custom Server with Environment Variables

export MCP_WRAPPED_SERVER_COMMAND=node
export MCP_WRAPPED_SERVER_ARGS="./my-custom-server.js,--port,3000"
export MCP_WRAPPED_ENV_API_KEY=your-secret-key
export MCP_WRAPPED_ENV_DEBUG=true
export MCP_LOG_FILE=./logs/custom-server.log
npm start

Example 3: Wrap Python Server

export MCP_WRAPPED_SERVER_COMMAND=python
export MCP_WRAPPED_SERVER_ARGS="-m,my_mcp_module"
export MCP_WRAPPED_ENV_PYTHONPATH=./src
export MCP_LOG_FILE=./logs/python-server.log
npm start

Troubleshooting

Server won’t start

  1. Check that MCP_WRAPPED_SERVER_COMMAND is set or config file exists
  2. Verify the wrapped server command is valid
  3. Check logs for error messages

Tools not showing up

  1. Ensure wrapped server is connecting successfully (check stderr output)
  2. Verify wrapped server exposes tools via tools/list
  3. Check log file for connection errors

Logging not working

  1. Verify MCP_LOG_FILE path is writable
  2. Check directory exists (will be created automatically)
  3. Ensure MCP_LOG_TOOL_CALLS and MCP_LOG_TOOL_RESULTS are not set to false

Architecture

MCP Client (e.g. Claude)
    ↕ stdio (JSON-RPC)
MCP Wrapper Server
    ↕ stdio (JSON-RPC)  → Logs to file
Wrapped MCP Server

The wrapper server:

  1. Receives requests from MCP client via stdio
  2. Forwards requests to wrapped server
  3. Logs all I/O operations
  4. Returns responses to MCP client

Security Notes

Performance

License

MIT