Ghost Security MCP Server

A Model Context Protocol (MCP) server for the Ghost Security API, providing secure access to security findings and repository data through standardized tools.

Features

• Security Findings Management: Query, retrieve, and update security findings
• Repository Analysis: Access repository data and associated findings
• Universal MCP Compatibility: Works with any MCP-compatible client or application
• Bundled CLI Chatbot: Includes a simple chatbot for quick interaction
• Comprehensive API Coverage: Full support for Ghost Security API (V2) endpoints
• Type Safety: Complete TypeScript implementation with proper typing
• Error Handling: Robust error handling and validation

Installation

Quick Install for Claude Code CLI

Option 1: Interactive Installer (Easiest)

# Clone and build
git clone https://github.com/ghostsecurity/ghost-mcp-server
cd ghost-mcp-server
npm install && npm run build

# Run interactive installer (prompts for API key)
npm run install:interactive

Option 2: Automated Setup Script

# Clone and build
git clone https://github.com/ghostsecurity/ghost-mcp-server
cd ghost-mcp-server
npm install && npm run build

# Run setup script with your API key
./setup-claude-code.sh YOUR_API_KEY

# Optional: Scope to a specific repository
./setup-claude-code.sh YOUR_API_KEY YOUR_REPO_ID

Option 3: Manual Setup

# Clone and build
git clone https://github.com/ghostsecurity/ghost-mcp-server
cd ghost-mcp-server
npm install && npm run build

# Add to Claude Code
claude mcp add --transport stdio --scope user ghost-security -- node $(pwd)/dist/index.js

# Then edit ~/.claude.json and add under mcpServers.ghost-security.env:
# {
#   "GHOST_SECURITY_API_KEY": "your-api-key",
#   "GHOST_SECURITY_BASE_URL": "https://api.ghostsecurity.ai/v2"
# }

Option 4: From npm (Coming Soon)

Once published to npm, installation will be even simpler:

claude mcp add --transport stdio --scope user ghost-security -- npx ghostsecurity-mcp

Then add your API key to ~/.claude.json:

{
  "mcpServers": {
    "ghost-security": {
      "env": {
        "GHOST_SECURITY_API_KEY": "your-api-key-here",
        "GHOST_SECURITY_BASE_URL": "https://api.ghostsecurity.ai/v2"
      }
    }
  }
}

Standard Installation (All MCP Clients)

1. Clone this repository:

git clone <repository-url>
cd ghost-mcp-server

2. Install dependencies:

npm install

3. Build the project:

npm run build

Usage

Configuration

The server requires a Ghost Security API key to be provided at startup. You can provide it in two ways:

Option 1: Environment Variable (Recommended)

export GHOST_SECURITY_API_KEY="your-ghost-security-api-key"
export GHOST_SECURITY_BASE_URL="https://api.ghostsecurity.ai/v2"  # optional, defaults to v2
export GHOST_SECURITY_REPO_ID="your-repository-id"  # optional - scope to specific repo

Option 2: Command Line Argument

node dist/index.js "your-ghost-security-api-key" "your-repository-id"

Note: Repository ID is optional. If provided, all operations will be scoped to that repository.

Running the Server

For development:

# Set environment variable first
export GHOST_SECURITY_API_KEY="your-api-key"
npm run dev

For production:

# Either with environment variable
export GHOST_SECURITY_API_KEY="your-api-key"
npm start

# Or with command line argument
npm run build
node dist/index.js "your-api-key"

CLI Chatbot

This project includes a simple CLI chatbot powered by Anthropic's Claude API that can interact with the MCP server.

export ANTHROPIC_API_KEY="your-anthropic-api-key"
export GHOST_SECURITY_API_KEY="your-ghost-api-key"
npm run chat

Adding to Any MCP Client

This server follows the standard MCP configuration format. Here are examples for different clients:

Standard MCP Configuration (Claude Desktop, ChatGPT, etc.)

{
  "mcpServers": {
    "ghostsecurity": {
      "command": "node",
      "args": ["/path/to/ghost-mcp-server/dist/index.js"],
      "env": {
        "GHOST_SECURITY_API_KEY": "your-ghost-security-api-key",
        "GHOST_SECURITY_REPO_ID": "your-repository-id"
      }
    }
  }
}

Environment Variable Setup (Universal)

For any MCP client that supports environment variables:

export GHOST_SECURITY_API_KEY="your-ghost-security-api-key"
export GHOST_SECURITY_BASE_URL="https://api.ghostsecurity.ai/v2"
export GHOST_SECURITY_REPO_ID="your-repository-id"

Repository Scoping

When a repository ID is configured via GHOST_SECURITY_REPO_ID environment variable or CLI argument:

• ghostsecurity_get_findings returns findings only for that repository
• ghostsecurity_get_repositories returns only the configured repository
• ghostsecurity_get_repository_findings uses the configured repository as default (repoId parameter becomes optional)

Available Tools

Security Findings

ghostsecurity_get_findings

Get security findings with optional filtering and pagination.

Parameters:

• cursor (string, optional): Pagination cursor
• sort (string, optional): Sort field (created_at, updated_at)
• order (string, optional): Sort order (asc, desc)
• size (number, optional): Page size (1-1000)
• status (string, optional): Filter by status
• repo_id (string, optional): Filter by repository ID
• project_id (string, optional): Filter by project ID

ghostsecurity_get_finding

Get a specific security finding by ID.

Parameters:

• id (string, required): Finding ID
• repoId (string, required): Repository ID associated with the finding
• projectId (string, required): Project ID associated with the finding

ghostsecurity_update_finding_status

Update the status of a security finding.

Parameters:

• id (string, required): Finding ID
• repoId (string, required): Repository ID associated with the finding
• projectId (string, required): Project ID associated with the finding
• status (string, required): New status for the finding

Repositories

ghostsecurity_get_repositories

Get repositories with optional filtering and pagination.

Parameters:

• cursor (string, optional): Pagination cursor
• sort (string, optional): Sort field (created_at, updated_at, last_committed_at)
• order (string, optional): Sort order (asc, desc)
• size (number, optional): Page size (1-1000)

ghostsecurity_get_repository

Get a specific repository by ID.

Parameters:

• id (string, required): Repository ID

ghostsecurity_get_repository_findings

Get security findings for a specific repository.

Parameters:

• repoId (string, optional*): Repository ID (*required unless GHOST_SECURITY_REPO_ID is configured)
• cursor (string, optional): Pagination cursor
• sort (string, optional): Sort field (created_at, updated_at)
• order (string, optional): Sort order (asc, desc)
• size (number, optional): Page size (1-1000)

Publishing to MCP Registry

This server is configured for publishing to the MCP Registry.

1. Install Publisher CLI:

   brew install mcp-publisher
   

2. Login:

   mcp-publisher login github
   

3. Publish:

   mcp-publisher publish
   

The server.json file contains the necessary metadata. Ensure you have published the package to NPM before publishing to the registry.

Development

Scripts

• npm run dev: Run in development mode with hot reload
• npm run build: Build TypeScript to JavaScript
• npm start: Run the built server
• npm run chat: Run the CLI chatbot

Project Structure

src/
├── index.ts          # Main MCP server implementation
├── ghost-client.ts   # Ghost Security API client (V2)
├── types.ts          # TypeScript type definitions
└── chatbot.ts        # CLI Chatbot implementation

API Reference

This MCP server provides a complete interface to the Ghost Security API V2. For detailed API documentation, visit: https://docs.ghostsecurity.ai/api-reference/introduction

License

MIT