ghost-mcp-server

ghostsecurity/ghost-mcp-server

3.2

If you are the rightful owner of ghost-mcp-server and would like to certify it and/or have it hosted online, please leave a comment on the right or send an email to dayong@mcphub.com.

The Ghost Security MCP Server is a Model Context Protocol server designed to interface with the Ghost Security API, providing secure and standardized access to security findings and repository data.

Tools
7
Resources
0
Prompts
0

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
  1. Install dependencies:
npm install
  1. 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