Beagle Security MCP Server

This is a Model Context Protocol (MCP) server that provides integration with the Beagle Security API. It allows you to manage projects, applications, and automated security testing through the Beagle Security platform.

Features

• Project Management: Create, modify, list, and delete projects

• Application Management: Create, get, modify, list, and delete applications

• Domain Verification: Get verification signatures and verify domain ownership with multiple signature types

• Security Testing: Start, monitor, stop, and retrieve results from automated penetration tests

• Team Support: Work with team projects and tests

Installation

Option 1: Docker (Recommended)

1. Clone this repository

2. Set up your environment variables:

   cp .env.example .env
   # Edit .env with your API token

3. Build and run with Docker:

   npm run docker:build
   npm run docker:run

Or use Docker Compose:

docker-compose up -d

Option 2: Local Installation

1. Clone this repository

2. Install dependencies:

   npm install

3. Build the project:

   npm run build

Configuration

Environment Variables

Set your Beagle Security API token as an environment variable:

export BEAGLE_SECURITY_API_TOKEN=your_api_token_here

You can obtain an API token from your Beagle Security account settings (Profile → Personal access token).

MCP Configuration

Docker Configuration

Add the server to your MCP configuration file:

{
  "mcpServers": {
    "beagle-security": {
      "command": "docker",
      "args": [
        "run", 
        "--rm", 
        "-i", 
        "--env", "BEAGLE_SECURITY_API_TOKEN=your_api_token_here",
        "--env", "NODE_ENV=production",
        "mcp/beagle-security-mcp-server"
      ]
    }
  }
}

Local Configuration

For local installations:

{
  "mcpServers": {
    "beagle-security": {
      "command": "node",
      "args": ["path/to/beagle-security-mcp-server/build/index.js"],
      "env": {
        "BEAGLE_SECURITY_API_TOKEN": "your_api_token_here"
      }
    }
  }
}

Available Tools (18 Total)

Project Management (4 tools)

• beagle_create_project: Create a new project

• beagle_modify_project: Modify an existing project

• beagle_list_projects: List all projects and applications

• beagle_delete_project: Delete a project

Application Management (5 tools)

• beagle_create_application: Create a new application in a project

• beagle_get_application: Get application details by token

• beagle_modify_application: Modify an existing application

• beagle_list_applications: List all applications under a project

• beagle_delete_application: Delete an application

Domain Verification (2 tools)

• beagle_get_domain_signature: Get domain verification signature

• beagle_verify_domain: Complete domain verification with FILE, DNS, or API signature types

Security Testing (7 tools)

• beagle_start_test: Start an automated penetration test

• beagle_get_test_status: Get the status of a running test

• beagle_stop_test: Stop a running test

• beagle_get_test_result: Get detailed test results in JSON format

• beagle_list_test_sessions: List all test sessions for an application

• beagle_list_running_tests: List all running tests for user or team (supports team filtering)

Testing

Comprehensive Test Suite

Run all tests to validate functionality:

# Run complete test suite (recommended)
npm run test:all

# Test individual components
npm run test:tools          # Test all 18 MCP tools
npm run test:integration    # Integration & API tests
npm run test                # Unit tests

# Test with real API (requires token)
BEAGLE_SECURITY_API_TOKEN=your_token npm run test:all

Test Features

• Tool Validation: Tests all 18 tools with proper parameters

• API Integration: Live API testing when credentials provided

• Error Handling: Validates error scenarios and edge cases

• Cross-Platform: Works on Linux, macOS, and Windows

• Docker Testing: Validates container functionality

For detailed testing information, see TESTING.md.

Development

Docker Development

# Build Docker image
npm run docker:build

# Run with Docker
npm run docker:run

# Use Docker Compose
npm run docker:compose:up

# View logs
npm run docker:compose:logs

# Stop services
npm run docker:compose:down

Local Development

# Running in Development Mode
npm run dev

# Building
npm run build

# Starting the Server
npm start

API Reference

This server implements the Beagle Security API v2.0. For detailed API documentation, visit: https://beaglesecurity.com/developer/apidoc

API Compatibility

This server implements Beagle Security API v2.0 with:

• ✅ All endpoints verified against official documentation

• ✅ Correct parameter naming (camelCase format)

• ✅ Proper error handling for all API response codes

• ✅ Latest API features including domain verification types

Error Handling

The server includes comprehensive error handling for:

• Authentication errors (invalid API tokens)

• HTTP errors (network issues, server errors)

• Validation errors (missing required parameters)

• API-specific errors (returned by Beagle Security)

• Cross-platform compatibility issues

Security Considerations

• Keep your API token secure and never commit it to version control

• Use environment variables or secure configuration management

• Ensure proper scopes are set when generating API tokens

• Monitor API usage to detect unauthorized access

Troubleshooting

Common Issues

1. Server won't start: Run npm run build to check for build errors

2. API calls failing: Verify your BEAGLE_SECURITY_API_TOKEN is valid

3. Docker issues: Ensure Docker is installed and running

4. macOS timeout errors: Install with brew install coreutils or tests will auto-fallback

Getting Help

• Run the test suite: npm run test:all

• Check the logs in development mode: NODE_ENV=development npm start

• Review TESTING.md for detailed troubleshooting

API Reference

Complete API documentation: https://beaglesecurity.com/developer/apidoc

License

MIT License