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:

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:

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:

Local Configuration

For local installations:

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:

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

Local Development

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