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

Variable	Default	Description
HOUND_URL	http://localhost:6080	Hound server URL
HOUND_TIMEOUT	30000	Request timeout (ms)
GITEA_URL	-	Gitea server URL (for file context)
GITEA_TOKEN	-	Gitea API token (for private repos)
GITEA_TIMEOUT	10000	Gitea API timeout (ms)
GITHUB_URL	https://github.com	GitHub URL (for Enterprise, otherwise defaults)
GITHUB_TOKEN	-	GitHub personal access token (for private repos)
GITHUB_TIMEOUT	10000	GitHub API timeout (ms)
MCP_PORT	3000	HTTP server port (HTTP mode only)
CORS_ALLOWED_ORIGIN	-	Allowed CORS origin (leave empty for permissive dev mode)
HOUND_CONFIG_DIR	-	Path to Hound config directory (for auto-indexing)
HOUND_WEBHOOK_SECRET	-	Secret for Gitea webhook signature verification

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.

Parameter	Type	Required	Default	Description
query	string	Yes	-	Regex pattern (e.g., validateJWT|verifyToken, func\s+\w+)
repos	string	No	*	Comma-separated repo names (e.g., owner/repo) or * for all
files	string	No	-	Glob pattern filter (e.g., *.ts, src/*.js)
ignore_case	boolean	No	false	Case-insensitive search
limit	number	No	20	Results per page (1-100)
offset	number	No	0	Skip N results for pagination

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.

Parameter	Type	Required	Default	Description
repo	string	Yes	-	Repository name (e.g., owner/repo)
file	string	Yes	-	File path (e.g., src/index.ts)
line	number	Yes	-	Center line number
context	number	No	10	Lines before/after (max 50)

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

Endpoint	Method	Description
/.well-known/oauth-authorization-server	GET	OAuth2 AS metadata (RFC 8414)
/.well-known/oauth-protected-resource	GET	Resource metadata (RFC 9728)
/oauth/authorize	GET	Authorization page
/oauth/authorize	POST	Approve authorization
/oauth/token	POST	Token exchange
/oauth/register	POST	Dynamic client registration (RFC 7591)

MCP Endpoints

Endpoint	Method	Description
/ or /sse	GET	SSE transport (Accept: text/event-stream)
/messages	POST	Message endpoint for SSE transport
/	POST	Streamable HTTP transport
/health	GET	Health check (no auth required)

Admin Endpoints

Endpoint	Method	Auth	Description
/webhook/gitea	POST	Webhook secret	Gitea webhook receiver
/admin/sync	POST	Bearer token	Manual Hound sync trigger

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