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.

<table> <tr> <td width="33%" align="center">

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.

</td> <td width="33%" align="center">

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.

</td> <td width="33%" align="center">

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.

</td> </tr> </table>

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