MCP Auditor

English | 中文

A TypeScript tool for auditing all interactions with MCP (Model Context Protocol) servers. It intercepts and logs all I/O operations from MCP servers through a transparent proxy approach, generating comprehensive audit logs to help developers debug, monitor, and ensure compliance in MCP applications.

Quick Links

• 📚 Full Documentation
• 🌏 中文文档
• 🖥️ Server Documentation
• 📝 Examples
• 📋 Changelog

Features

• ✅ Wrap MCP Servers - Connect to existing MCP servers as a client
• ✅ Expose All Capabilities - Expose all tools, resources, and prompts from the wrapped server
• ✅ Proxy Functionality - Transparently forward all MCP operations
• ✅ Comprehensive Logging - Record all input/output interactions (tools, resources, prompts)
• ✅ Multiple Log Formats - Structured (detailed) or JSON-RPC (protocol messages)
• ✅ Stdio Transport - Run as a standalone MCP server with stdio communication support

Quick Start

Installation

As a library (recommended):

npm install mcp-auditor

From source:

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

As a global CLI:

npm install -g mcp-auditor

Run as Server

Using global CLI (after npm install -g mcp-auditor):

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

# Run the server
mcp-auditor

Using configuration file:

# Create config.json
cat > config.json << EOF
{
  "name": "mcp-auditor-server",
  "version": "1.0.0",
  "wrappedServer": {
    "serverCommand": "npx",
    "serverArgs": ["-y", "@modelcontextprotocol/server-filesystem", "/tmp"],
    "logFilePath": "./logs/mcp-server.log"
  }
}
EOF

# Run with config
export MCP_CONFIG_FILE=./config.json
mcp-auditor

From source:

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

# Start the server
npm start

Use as Library

import { MCPWrapper } from 'mcp-auditor';

const wrapper = new MCPWrapper({
  serverCommand: 'npx',
  serverArgs: ['-y', '@modelcontextprotocol/server-filesystem', '/tmp'],
  logFilePath: './logs/mcp-wrapper.log'
});

await wrapper.connect();
const tools = wrapper.getTools();
const result = await wrapper.callTool('read_file', { path: '/tmp/example.txt' });
await wrapper.disconnect();

Documentation

For comprehensive documentation, please see:

• English Documentation
• Server Mode Documentation
• 中文文档

Project Structure

mcp-auditor/
├── src/
│   ├── core/              # Core wrapper functionality
│   │   ├── wrapper.ts     # Main MCPWrapper class
│   │   ├── logger.ts      # Logger implementation
│   │   └── types.ts       # TypeScript types
│   ├── server/            # Server-specific code
│   │   ├── server.ts      # MCP server implementation
│   │   └── config.ts      # Configuration loader
│   └── index.ts           # Main entry point
├── examples/
│   ├── library/           # Library usage examples
│   └── server/            # Server usage examples
├── docs/                  # Documentation
├── dist/                  # Compiled output
└── logs/                  # Log files

License

MIT

For detailed usage instructions, API documentation, and examples, please refer to the full documentation.