Gooseworks MCP

An Express server that exposes tools through the Model Context Protocol (MCP) Streamable HTTP transport, including a set of GitHub tools.

The MCP endpoint is:

http://localhost:4000/mcp

Every request must include the bearer token configured by MCP_AUTH_TOKEN.

Requirements

• Node.js v25.2.1
• pnpm 11.5.3
• Docker Engine and Docker Compose v2 for container deployment
• A GitHub personal access token with the permissions required by the tools you plan to use

Configuration

The server loads variables from a local .env file or the process environment:

Variable	Required	Default	Description
PORT	No	4000	Port on which the HTTP server listens
GITHUB_TOKEN	Yes	None	GitHub personal access token used by Octokit
MCP_AUTH_TOKEN	Yes	None	Bearer token required for every MCP request

Create a local environment file from the template:

cp .env.template .env

Edit .env and replace both placeholder token values. Use a long, randomly generated value for MCP_AUTH_TOKEN, and grant the GitHub token only the permissions needed by this server. Never commit .env or paste either token into a public issue, log, or image.

Run Locally

1. Install dependencies:

   pnpm install
   

2. Create and configure .env as described above.

3. Start the server:

   pnpm start
   

   This runs the same entrypoint as pnpm exec tsx src/index.ts.

For development with automatic restart after source changes, use:

pnpm dev

To check the TypeScript project without emitting files:

pnpm typecheck

The server is ready when the console reports that it is active on http://localhost:<PORT>/mcp. Configure your MCP client to use that URL and send:

Authorization: Bearer <MCP_AUTH_TOKEN>

Deploy With Docker Compose

1. Install Docker Engine with Docker Compose v2 on the host.

2. Clone this repository and enter its directory:

   git clone <repository-url>
   cd gooseworks-mcp
   

3. Create the deployment environment file:

   cp .env.template .env
   

4. Set GITHUB_TOKEN and a strong, private MCP_AUTH_TOKEN in .env. Set PORT if the service should listen on a different host/container port. The same value is used for both sides of the Compose port mapping.

5. Build and start the service in the background:

   docker compose up --build -d
   

6. Follow the service logs or stop it when needed:

   docker compose logs -f gooseworks-mcp
   docker compose down
   

The Compose configuration passes the three supported variables into the container and fails early if either required token is missing. For a public deployment, place the service behind an HTTPS reverse proxy and keep port 4000 or your chosen PORT private when possible. MCP clients should use the proxy's HTTPS /mcp URL and the configured bearer token.

Available Tools

The server registers the following tools:

GitHub

• Reading the authenticated profile
• Listing repositories, branches, and commits
• Searching code
• Reading file contents
• Creating issues
• Creating pull requests

License

This project is licensed under the MIT License. It is free to use, fork, modify, and redistribute for any purpose, subject to the license terms.