MCP-Hound

MCP server for Hound code search integration. Exposes Hound's regex-based code search to Claude Code and other MCP-compatible AI agents.

Note: This is a thin wrapper around Hound's API. The query parameter accepts regex patterns (Hound's native format). AI agents consuming this MCP server are responsible for synthesizing appropriate regex from user intent.

Features

• hound_search - Search code across all indexed repositories with regex patterns and pagination

• hound_repos - List all repositories indexed by Hound

• hound_file_context - Get extended context around a code match with Gitea/GitHub deep links

• Auto-indexing - Webhook support for automatic Hound re-indexing when repos change

Requirements

• Node.js 20+

• Running Hound instance

• Gitea or GitHub instance (Hound indexes repositories from these providers)

• (Optional) API token for file context lookups and private repository access

Installation

# From npm (when published)
npm install -g @jmagly/mcp-hound

# From source
git clone https://github.com/jmagly/mcp-hound.git
cd mcp-hound
npm install
npm run build

Configuration

Environment Variables

Note: Configure either Gitea OR GitHub (required - Hound indexes repos from these). If both are set, Gitea takes priority. Tokens are optional but required for private repos and the hound_file_context tool.

Claude Code Integration

Add to ~/.claude/settings.json:

{
  "mcpServers": {
    "hound": {
      "command": "node",
      "args": ["/path/to/mcp-hound/dist/index.js"],
      "env": {
        "HOUND_URL": "http://localhost:6080"
      }
    }
  }
}

Or using npx (when published):

{
  "mcpServers": {
    "hound": {
      "command": "npx",
      "args": ["-y", "@jmagly/mcp-hound"],
      "env": {
        "HOUND_URL": "http://localhost:6080"
      }
    }
  }
}

Usage

Once configured, the MCP tools are available in Claude Code. The AI agent translates user intent into regex queries:

Search Code

User: Find where JWT tokens are validated in the codebase

Claude synthesizes regex and calls:
  hound_search({ query: "validateJWT|verifyToken|jwt\\.verify", files: "*.ts" })

Paginate Through Results

User: Show me the next page of results

Claude uses offset from previous response:
  hound_search({ query: "TODO|FIXME", offset: 20, limit: 20 })

List Repositories

User: What repositories are indexed?

Claude calls:
  hound_repos()

Get File Context

User: Show me more context around that match

Claude calls:
  hound_file_context({ repo: "myorg/myrepo", file: "src/auth.ts", line: 42 })

Tools Reference

hound_search

Search code across repositories with pagination support.

Response includes pagination metadata:

• totalMatches - Total matches found

• count - Results in this response

• hasMore - Whether more results exist

• nextOffset - Offset for next page (use with subsequent request)

hound_repos

List all indexed repositories. No parameters required.

hound_file_context

Get extended context around a specific line.

Deployment

Transport Modes

MCP-Hound supports two transport modes:

• stdio (default): For local invocation by Claude Code

• http: For remote/service deployment with OAuth2 authentication

Local Mode (stdio)

Add to ~/.claude.json:

{
  "mcpServers": {
    "hound": {
      "command": "node",
      "args": ["/path/to/mcp-hound/dist/index.js"],
      "env": {
        "HOUND_URL": "http://localhost:6080"
      }
    }
  }
}

Docker Deployment

MCP-Hound provides Docker images for containerized deployment:

# Build production image
docker compose build mcp-hound

# Run production container
docker compose up -d mcp-hound

# Run with environment variables
docker run -d \
  -p 3100:3000 \
  -e HOUND_URL=http://hound:6080 \
  -e GITHUB_TOKEN=your_token \
  jmagly/mcp-hound:latest

# Development with live reload
docker compose --profile dev up dev

See docker-compose.yml for full configuration options.

Remote Mode (HTTP with OAuth2)

For remote deployment, MCP-Hound provides OAuth2 authentication with:

• Dynamic client registration (RFC 7591)

• Authorization code flow with PKCE

• Refresh token support

1. System Service Setup

# Clone and build
git clone https://github.com/jmagly/mcp-hound.git
cd mcp-hound
npm install
npm run build

# Create directories
sudo mkdir -p /opt/mcp-hound /etc/mcp-hound

# Copy files
sudo cp -r dist package.json /opt/mcp-hound/
sudo cp -r node_modules /opt/mcp-hound/

# Create environment file
sudo tee /etc/mcp-hound/env << 'EOF'
HOUND_URL=https://your-hound-instance.example.com
GITEA_URL=https://your-gitea-instance.example.com
GITEA_TOKEN=your-gitea-api-token
MCP_CREDENTIALS_FILE=/etc/mcp-hound/clients.json

# Auto-indexing (optional)
HOUND_CONFIG_DIR=/path/to/hound/config
# HOUND_WEBHOOK_SECRET=optional-webhook-secret
EOF

# Create empty clients file
echo '[]' | sudo tee /etc/mcp-hound/clients.json

2. Systemd Service

Create /etc/systemd/system/mcp-hound.service:

[Unit]
Description=MCP-Hound Code Search Server
After=network.target

[Service]
Type=simple
WorkingDirectory=/opt/mcp-hound
ExecStart=/usr/bin/node /opt/mcp-hound/dist/index.js --http --port 3100
Restart=always
RestartSec=10
EnvironmentFile=/etc/mcp-hound/env
StandardOutput=journal
StandardError=journal
SyslogIdentifier=mcp-hound

[Install]
WantedBy=multi-user.target

Enable and start:

sudo systemctl daemon-reload
sudo systemctl enable mcp-hound
sudo systemctl start mcp-hound

3. Nginx Reverse Proxy (HTTPS)

Create /etc/nginx/sites-available/mcp-hound:

server {
    listen 443 ssl http2;
    server_name mcp-hound.example.com;

    ssl_certificate /path/to/cert.pem;
    ssl_certificate_key /path/to/key.pem;

    # Required for SSE (Server-Sent Events)
    proxy_http_version 1.1;
    proxy_set_header Connection "";
    proxy_buffering off;
    proxy_cache off;
    proxy_read_timeout 300s;

    location / {
        proxy_pass http://127.0.0.1:3100;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
    }
}

4. Claude Code Configuration

Add to ~/.claude.json on the client machine:

{
  "mcpServers": {
    "hound": {
      "url": "https://mcp-hound.example.com/"
    }
  }
}

Then authenticate:

claude
> /mcp
# Select "Authenticate" for the Hound server
# Browser opens → Click "Authorize"
# Connection established

Auto-Indexing with Webhooks

MCP-Hound can automatically update the Hound index when repositories are created or deleted in Gitea.

Setup

1. Configure environment variables:

   HOUND_CONFIG_DIR=/path/to/hound/deployments
   HOUND_WEBHOOK_SECRET=optional-secret  # For signature verification

2. Add a webhook in Gitea (Organization or Repository settings):

   • URL: https://mcp-hound.example.com/webhook/gitea

   • Content Type: application/json

   • Events: Repository (Created, Deleted)

   • Secret: Same as HOUND_WEBHOOK_SECRET (optional)

Manual Sync

Trigger a manual sync via authenticated API:

curl -X POST https://mcp-hound.example.com/admin/sync \
  -H "Authorization: Bearer YOUR_TOKEN"

API Endpoints

OAuth2 Endpoints

MCP Endpoints

Admin Endpoints

Service Management

# Check status
sudo systemctl status mcp-hound

# View logs
sudo journalctl -u mcp-hound -f

# Restart after config changes
sudo systemctl restart mcp-hound

Client Credentials CLI

For manual client management:

# Create a client
mcp-hound-auth create "My Client Name"

# List clients
mcp-hound-auth list

# Revoke a client
mcp-hound-auth revoke mcp_xxxxx

Note: Tokens are stored in-memory. Server restarts require re-authentication.

Error Messages

MCP-Hound provides helpful error messages for AI agents:

Empty search results:

No matches found. Try:
- A different regex pattern
- Removing the files filter
- Using ignore_case: true
- Checking repos with hound_repos()

Timeout errors:

Search timed out.

Try:
- A more specific regex pattern
- Limiting to specific repos: repos: "owner/repo"
- Adding a files filter: files: "*.ts"

File not found:

File not found: owner/repo/path/to/file.ts (branch: main)

Development

# Install dependencies
npm install

# Build
npm run build

# Run in development mode
npm run dev

# Run tests
npm test

# Type check
npm run typecheck

# Lint
npm run lint

# Format
npm run format

See CONTRIBUTING.md for detailed development guidelines.

Project Status

This project is in active development. See the issues for planned features and known issues.

❤️ Sponsors

MCP-Hound is made possible by our sponsors.

Roko Network

The Temporal Layer for Web3

Building enterprise-grade timing infrastructure for blockchain applications. Roko Network enables developers to create decentralized systems with nanosecond-level precision.

Selfient

No-Code Smart Contracts for Everyone

Democratizing Web3 by making blockchain-based agreements accessible to all. Selfient empowers creators, freelancers, and businesses to create enforceable smart contracts without writing code.

Integro Labs

AI-Powered Automation Solutions

Harnessing the transformative potential of AI and blockchain to shape digital automation. Integro Labs delivers custom solutions for the age of intelligent systems.

Interested in sponsoring? Contact us to learn how your organization can support open-source AI tooling.

Acknowledgments

MCP-Hound is built on top of Hound, the lightning-fast code search engine created by Etsy. Hound makes it possible to search across thousands of repositories in milliseconds using regular expressions.

License

MIT