https://github.com/devinoldenburg/shannon-mcp
Model Context Protocol server bringing Shannon Lite security to your AI agent
https://github.com/devinoldenburg/shannon-mcp
ai-agent mcp mcp-server security security-automation shannon shannon-ai shannon-lite typescript
Last synced: 1 day ago
JSON representation
Model Context Protocol server bringing Shannon Lite security to your AI agent
- Host: GitHub
- URL: https://github.com/devinoldenburg/shannon-mcp
- Owner: devinoldenburg
- License: mit
- Created: 2026-04-17T16:39:26.000Z (3 months ago)
- Default Branch: main
- Last Pushed: 2026-06-16T23:36:59.000Z (about 1 month ago)
- Last Synced: 2026-07-07T12:30:53.041Z (16 days ago)
- Topics: ai-agent, mcp, mcp-server, security, security-automation, shannon, shannon-ai, shannon-lite, typescript
- Language: TypeScript
- Homepage:
- Size: 53.7 KB
- Stars: 1
- Watchers: 0
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
Shannon Lite MCP
Model Context Protocol server for end-to-end Shannon Lite security workflows
This package enables AI assistants and applications to configure Shannon, start scans, monitor runtime, inspect workspaces, and read reports programmatically.
## Features
- Full Shannon Lite workflow support through MCP tools
- Built-in config management for `~/.shannon/config.toml`
- Scan orchestration (`start`, `status`, `workspaces`, logs, report reads)
- Safe destructive operations with explicit confirmation tokens
- Smart CLI execution (`shannon` binary or fallback to `npx @keygraph/shannon`)
- TypeScript implementation with strict Zod validation
## Setup
### Prerequisites
- Node.js 18+
- Docker (daemon running)
- Shannon CLI access (`shannon` in `PATH` or `npx` available)
### MCP Configuration
If you are running this repo locally (unpublished package), build first:
```bash
npm install
npm run build
```
Then use command `node` with args `[/absolute/path/to/shannon-mcp/dist/index.js]` in your MCP client configuration.
#### For Claude Desktop
Add to your Claude Desktop configuration file (`~/Library/Application Support/Claude/claude_desktop_config.json` on macOS):
```json
{
"mcpServers": {
"shannon-lite": {
"command": "npx",
"args": ["-y", "shannon-lite-mcp"]
}
}
}
```
#### For Cursor
Add the configuration to your Cursor settings:
```json
{
"mcpServers": {
"shannon-lite": {
"command": "npx",
"args": ["-y", "shannon-lite-mcp"]
}
}
}
```
#### For Windsurf
Add the configuration to your Windsurf settings:
```json
{
"mcpServers": {
"shannon-lite": {
"command": "npx",
"args": ["-y", "shannon-lite-mcp"]
}
}
}
```
#### For Warp
Add the following to your Warp session setup:
```json
{
"shannon-lite": {
"command": "npx",
"args": ["-y", "shannon-lite-mcp"],
"working_directory": null,
"start_on_launch": true
}
}
```
#### For Other MCP Clients
Use standard MCP server settings:
- **Command**: `npx -y shannon-lite-mcp` or `node /path/to/shannon-mcp/dist/index.js`
- **Transport**: stdio
## Available MCP Tools
- `shannon_health` - Check Docker/Node/CLI readiness, config, and workspace state
- `shannon_config_set` - Write `~/.shannon/config.toml` for `anthropic`, `custom_base_url`, `bedrock`, `vertex`, or `router`
- `shannon_config_get` - Read current config with secret masking
- `shannon_start_scan` - Start a scan with `url`, `repo`, and optional `config`, `workspace`, `output`, `pipeline_testing`, `router`
- `shannon_status` - Get Temporal + worker runtime status
- `shannon_list_workspaces` - List known Shannon workspaces
- `shannon_get_workspace` - Return detailed workspace/session metadata
- `shannon_read_workflow_log` - Read workspace `workflow.log` (tail by default)
- `shannon_read_report` - Read final report from workspace deliverables
- `shannon_stop` - Stop Shannon runtime (clean mode requires confirmation token)
- `shannon_uninstall` - Remove `~/.shannon` and stop runtime (requires confirmation token)
## Safety Notice
Shannon Lite can run real security test flows. Use only on systems you are authorized to test.
Destructive operations require exact confirmation tokens:
- `shannon_stop` with `clean=true`: `I_UNDERSTAND_THIS_WILL_REMOVE_SHANNON_DATA`
- `shannon_uninstall`: `DELETE_SHANNON_HOME_AND_STOP_SHANNON`
## Usage Examples
### Configure Anthropic API Key
```javascript
await mcp.callTool("shannon_config_set", {
provider: "anthropic",
auth_method: "api_key",
api_key: "sk-ant-..."
});
```
### Start a Scan
```javascript
await mcp.callTool("shannon_start_scan", {
url: "https://example.com",
repo: "/absolute/path/to/repo",
workspace: "q2-audit"
});
```
### Read Final Report
```javascript
await mcp.callTool("shannon_read_report", {
workspace: "q2-audit"
});
```
### Clean Stop (destructive)
```javascript
await mcp.callTool("shannon_stop", {
clean: true,
confirm_destructive: "I_UNDERSTAND_THIS_WILL_REMOVE_SHANNON_DATA"
});
```
## Development Setup
### Prerequisites
- Node.js 18+
- npm
### Local Development
1. **Install dependencies**:
```bash
npm install
```
2. **Build the project**:
```bash
npm run build
```
3. **Run in development mode**:
```bash
npm run dev
```
4. **Run tests**:
```bash
npm run test:run
```
## Contributing
1. Fork the repository
2. Create your feature branch (`git checkout -b feature/amazing-feature`)
3. Commit your changes (`git commit -m 'Add some amazing feature'`)
4. Push to the branch (`git push origin feature/amazing-feature`)
5. Open a Pull Request
## License
This project is licensed under the MIT License - see the `LICENSE` file for details.
## Links
- [Shannon (Keygraph)](https://github.com/KeygraphHQ/shannon)
- [Model Context Protocol Specification](https://spec.modelcontextprotocol.io/)
- [MCP TypeScript SDK](https://github.com/modelcontextprotocol/typescript-sdk)
## Support
- Create an issue for bug reports or feature requests
- Check existing issues before creating new ones
- Include reproduction steps, environment info, and relevant logs
---
Made with care for the security engineering community.