MCP Client & Server

A Model Context Protocol (MCP) project built with Bun and TypeScript.

The project includes:

• An MCP server exposing tools, prompts, and resources

• An MCP client that connects to the server over stdio

• Google Gemini integration through the Vercel AI SDK

• Redis for user data

• Interactive CLI menus for testing MCP functionality

Tech Stack

• Bun

• TypeScript

• Model Context Protocol (MCP)

• Vercel AI SDK

• Google Gemini

• Redis

• Zod

• Inquirer

Related MCP server: FastAPI + FastMCP + Gemini Integration

Project Structure

mcp/
├── src/
│   ├── client.ts
│   └── server.ts
├── docker-compose.yml
├── package.json
├── bun.lock
└── README.md

Requirements

Before running the project, make sure you have:

• Bun

• Docker

• A Google Gemini API key

Installation

Install the project dependencies:

bun install

Environment Variables

Create a .env file in the project root:

GEMINI_API_KEY=your_google_gemini_api_key

The server uses the following Redis connection by default:

redis://localhost:6379

You can optionally configure a different Redis connection:

REDIS_URL=redis://localhost:6379

Do not commit your .env file to the repository.

Start Redis

Redis is provided through Docker Compose.

Start Redis:

docker compose up -d

Check that the container is running:

docker ps

The container is named:

mcp-redis

Redis is available on:

localhost:6379

Stop Redis with:

docker compose down

Redis data is stored in the Docker volume:

redis-data

Run the MCP Server

Start the MCP server with:

bun run server:dev

The server uses stdio transport for MCP communication.

Run the MCP Client

Start the interactive client:

bun run client:dev

The client automatically starts the MCP server using:

bun run ./src/server.ts

After connecting, the client displays:

You are connected

You can then select one of the following options:

Query
Tools
Resources
Prompts

Query

The Query option sends a request to Google Gemini with access to the MCP tools exposed by the server.

For example:

Create a user with name Ivan and age 19 and email ivan@test.test

Gemini can use the available MCP tools to perform the requested operation.

Tools

The Tools option allows you to select and execute an MCP tool manually.

create-user

Creates a user with the following parameters:

name
age
email

Example:

name: Ivan
age: 19
email: ivan@test.test

create-random-user

Uses MCP sampling to generate user information and stores the generated user.

Resources

The Resources option allows you to access resources exposed by the MCP server.

users://all

Returns all users stored by the server.

users://{userId}/profile

Returns the profile associated with a user ID.

When selecting a resource containing {userId}, the client asks you to provide the value.

Prompts

The Prompts option displays prompts registered by the MCP server.

generate-fake-user

Generates a fake user with random details.

The client displays the prompt and allows you to execute it using Google Gemini.

MCP Inspector

The project includes the MCP Inspector for inspecting and interacting with the MCP server.

Start it with:

bun run server:inspect

Complete Setup

1. Install dependencies

bun install

2. Configure Gemini

Create .env:

GEMINI_API_KEY=your_google_gemini_api_key

3. Start Redis

docker compose up -d

4. Start the client

bun run client:dev

The client automatically starts the MCP server.

5. Choose an operation

Query
Tools
Resources
Prompts

Useful Commands

Redis

To access the Redis CLI:

docker exec -it mcp-redis redis-cli

List keys:

KEYS *

Inspect a user:

GET users:{userId}

The users:all key is a Redis Set, so use:

SMEMBERS users:all

Troubleshooting

Redis connection error

Make sure Redis is running:

docker ps

If the container is not running:

docker compose up -d

The default Redis connection is:

redis://localhost:6379

Redis WRONGTYPE error

If Redis reports:

WRONGTYPE Operation against a key holding the wrong kind of value

make sure you are using a Redis command that matches the key's data type.

For example, users:all is a Set:

SMEMBERS users:all

rather than:

GET users:all

Gemini API errors

Check that GEMINI_API_KEY is present in .env and contains a valid Google Gemini API key.

MCP connection errors

Make sure the MCP server can start:

bun run server:dev

Also verify that the client uses the correct server path:

const transport = new StdioClientTransport({
  command: "bun",
  args: ["run", "./src/server.ts"],
});