@rhofkens/mcp-quotes-server
Advanced tools
A Model Context Protocol (MCP) server that provides quotes based on user requests
A Model Context Protocol (MCP) server that provides quotes based on user requests. This server demonstrates the basic implementation of an MCP server using TypeScript and the official MCP SDK.
git clone <repository-url>
cd mcp-quotes-server
npm install
Set the SERPER_API_KEY environment variable with your API key from serper.dev:
export SERPER_API_KEY="your-serper-api-key-here"
You can also create a .env file in the project root:
echo "SERPER_API_KEY=your-serper-api-key-here" > .env
This server supports both stdio and HTTP transports. By default, it uses stdio transport for backwards compatibility. To enable HTTP transport, configure the following environment variables:
| Variable | Description | Default | Required |
|---|---|---|---|
MCP_HTTP_ENABLED | Enable HTTP transport | false | No |
MCP_HTTP_PORT | HTTP server port | 3000 | No |
MCP_HTTP_HOST | HTTP server host | localhost | No |
MCP_HTTP_ALLOWED_ORIGINS | Comma-separated CORS origins | http://localhost:3000 | No |
MCP_HTTP_ALLOWED_HOSTS | Comma-separated allowed hosts for DNS rebinding protection | localhost | No |
MCP_HTTPS_ENABLED | Enable HTTPS (requires certificates) | false | No |
MCP_HTTPS_CERT_PATH | Path to SSL certificate file | - | If HTTPS enabled |
MCP_HTTPS_KEY_PATH | Path to SSL private key file | - | If HTTPS enabled |
To run the server with HTTP transport:
# Enable HTTP transport on default port 3000
export MCP_HTTP_ENABLED=true
npm start
Or with custom configuration:
# Custom HTTP configuration
export MCP_HTTP_ENABLED=true
export MCP_HTTP_PORT=8080
export MCP_HTTP_HOST=0.0.0.0
export MCP_HTTP_ALLOWED_ORIGINS="https://example.com,https://app.example.com"
export MCP_HTTP_ALLOWED_HOSTS="localhost,127.0.0.1,example.com"
npm start
For production deployments with HTTPS:
# HTTPS configuration
export MCP_HTTP_ENABLED=true
export MCP_HTTPS_ENABLED=true
export MCP_HTTPS_CERT_PATH="/path/to/certificate.pem"
export MCP_HTTPS_KEY_PATH="/path/to/private-key.pem"
export MCP_HTTP_ALLOWED_ORIGINS="https://yourapp.com"
export MCP_HTTP_ALLOWED_HOSTS="yourapp.com"
npm start
The server automatically validates the Host header against allowed hosts to prevent DNS rebinding attacks.
Cross-Origin Resource Sharing (CORS) is configured to only allow requests from specified origins.
HTTP transport uses session-based communication with automatic cleanup of inactive sessions.
When HTTP transport is enabled, the server exposes the following endpoints:
POST /mcp - Main MCP communication endpointGET /mcp - Server-to-client notifications via Server-Sent EventsDELETE /mcp - Session terminationGET /health - Health check endpointGET /sessions - Session statistics (for monitoring)To compile the TypeScript code to JavaScript:
npm run build
This will create a dist directory with the compiled JavaScript files.
To start the MCP server, you have several options:
Option 1 - Using npm start (Recommended for development):
npm start
Option 2 - Using compiled JavaScript (Recommended for MCP inspector):
npm run build
node dist/start.js
Option 3 - Using ts-node directly:
npx ts-node src/start.ts
The server will start and listen for MCP connections via stdio transport.
For MCP Inspector Testing:
Use any of the above commands in your MCP client configuration. The most reliable option for MCP inspector is node dist/start.js after building the project.
To run the test suite:
npm test
To run tests with coverage:
npm test -- --coverage
To run linting checks:
npm run lint
To format code:
npm run format
get_quoteRetrieves real quotes from a specified person or topic using the Serper.dev API. Enhanced with support for requesting multiple quotes at once.
Parameters:
person (required): The name of the person to get a quote fromtopic (optional): The topic or subject for the quotenumberOfQuotes (optional): Number of quotes to retrieve (1-10, defaults to 1)Example Usage with MCP Client:
// Example 1: Single quote request
const result = await client.callTool({
name: "get_quote",
arguments: {
person: "Albert Einstein",
topic: "science",
},
});
// Expected response (real quote from Serper.dev):
{
content: [
{
type: "text",
text: "Science without religion is lame, religion without science is blind.",
},
];
}
// Example 2: Multiple quotes request
const multipleQuotes = await client.callTool({
name: "get_quote",
arguments: {
person: "Maya Angelou",
numberOfQuotes: 3,
},
});
// Expected response (formatted multiple quotes):
{
content: [
{
type: "text",
text: `1. "If you don't like something, change it. If you can't change it, change your attitude."
2. "There is no greater agony than bearing an untold story inside you."
3. "Try to be a rainbow in someone's cloud."`,
},
];
}
Parameter Validation:
The tool includes comprehensive parameter validation:
Error Handling:
The tool provides comprehensive error handling:
Logging:
All API requests and responses are logged to files for monitoring:
combined.log: All log entrieserrors.log: Error-level messages onlyprompt-template://quote-requestProvides a structured prompt template for quote requests that follows MCP resource standards.
Usage with MCP Client:
// List available resources
const resources = await client.listResources();
// Access the prompt template resource
const template = await client.readResource({
uri: "prompt-template://quote-request",
});
// The resource contains structured information about:
// - Parameter specifications (person, topic, numberOfQuotes)
// - Usage examples and best practices
// - Input validation requirements
Resource Content Structure:
{
"name": "Prompt Template for Quote Requests",
"description": "A structured template for requesting quotes from famous people with specific topics and quantities.",
"parameters": [
{
"name": "person",
"type": "string",
"required": true,
"description": "The name of the person to get quotes from"
},
{
"name": "topic",
"type": "string",
"required": false,
"description": "Optional topic to filter quotes by"
},
{
"name": "numberOfQuotes",
"type": "number",
"required": false,
"description": "Number of quotes to retrieve (1 to 10)"
}
],
"examples": [
{
"title": "Single Quote Request",
"parameters": {
"person": "Albert Einstein",
"topic": "imagination"
}
},
{
"title": "Multiple Quotes Request",
"parameters": {
"person": "Maya Angelou",
"numberOfQuotes": 5
}
}
]
}
To use this server with an MCP client via stdio transport:
import { Client } from "@modelcontextprotocol/sdk/client/index.js";
import { StdioClientTransport } from "@modelcontextprotocol/sdk/client/stdio.js";
// Create transport that runs this server
const transport = new StdioClientTransport({
command: "npm",
args: ["start"],
cwd: "/path/to/mcp-quotes-server",
});
// Create and connect client
const client = new Client({
name: "example-client",
version: "1.0.0",
});
await client.connect(transport);
// List available tools
const tools = await client.listTools();
console.log("Available tools:", tools);
// Call the get_quote tool
const result = await client.callTool({
name: "get_quote",
arguments: {
person: "Shakespeare",
topic: "love",
},
});
console.log("Quote result:", result);
To use this server with HTTP transport:
import { Client } from "@modelcontextprotocol/sdk/client/index.js";
import { StreamableHTTPClientTransport } from "@modelcontextprotocol/sdk/client/streamableHttp.js";
// Create HTTP transport
const transport = new StreamableHTTPClientTransport({
baseUrl: "http://localhost:3000",
});
// Create and connect client
const client = new Client({
name: "example-http-client",
version: "1.0.0",
});
await client.connect(transport);
// Use the same API as stdio transport
const tools = await client.listTools();
const result = await client.callTool({
name: "get_quote",
arguments: {
person: "Einstein",
topic: "imagination",
},
});
For secure HTTPS connections:
import { Client } from "@modelcontextprotocol/sdk/client/index.js";
import { StreamableHTTPClientTransport } from "@modelcontextprotocol/sdk/client/streamableHttp.js";
// Create HTTPS transport
const transport = new StreamableHTTPClientTransport({
baseUrl: "https://your-mcp-server.com",
headers: {
Authorization: "Bearer your-auth-token",
},
});
const client = new Client({
name: "secure-client",
version: "1.0.0",
});
await client.connect(transport);
The easiest way to test this MCP server is using the published NPM package:
npm install -g @modelcontextprotocol/inspector
mcp-inspector
npx@rhofkens/mcp-quotes-server@0.1.3If you want to test with local code changes:
npm install -g @modelcontextprotocol/inspector
npm run build
mcp-inspector
nodedist/start.jsOnce connected, you can:
get_quoteget_quote tool{"person": "Einstein", "topic": "science"}prompt-template://quote-requestnpm run buildSERPER_API_KEY environment variable is setTo use this MCP server with Claude Desktop, you need to configure it in your Claude Desktop settings:
Open Claude Desktop Configuration:
~/Library/Application Support/Claude/claude_desktop_config.json%APPDATA%/Claude/claude_desktop_config.json~/.config/Claude/claude_desktop_config.jsonAdd Server Configuration:
{
"mcpServers": {
"quotes-server": {
"command": "node",
"args": ["dist/start.js"],
"cwd": "/path/to/your/mcp-quotes-server",
"env": {
"SERPER_API_KEY": "your-serper-api-key-here"
}
}
}
}
If you prefer to use npm:
{
"mcpServers": {
"quotes-server": {
"command": "npm",
"args": ["start"],
"cwd": "/path/to/your/mcp-quotes-server",
"env": {
"SERPER_API_KEY": "your-serper-api-key-here"
}
}
}
}
After configuration and restarting Claude Desktop:
Verify Connection: Look for the MCP server icon in Claude Desktop
Use the get_quote Tool: Type messages like:
Access Resources: The prompt template resource will be available for structured requests
Issue: Error: Missing or invalid Serper API key
Solutions:
echo $SERPER_API_KEY.env file, ensure no spaces around the = signIssue: npm install fails or TypeScript compilation errors
Solutions:
node --versionnpm cache clean --forcenode_modules and reinstall: rm -rf node_modules && npm installnpm list typescriptIssue: MCP clients cannot connect to the server
Solutions:
npm run buildnode dist/start.jsIssue: No quotes returned or API errors
Solutions:
combined.log for detailed error informationIssue: HTTP server not starting or connection refused
Solutions:
lsof -i :3000 (replace 3000 with your port)Issue: Tests failing or coverage not meeting requirements
Solutions:
npm test -- --testNamePattern="specific test"Issue: Log files not created or logs not appearing
Solutions:
src/utils/logger.tsIf you continue to experience issues:
combined.log and errors.log for detailed error informationmcp-quotes-server/
├── src/
│ ├── index.ts # Main server entry point
│ ├── start.ts # Server startup script
│ ├── services/
│ │ ├── serper-service.ts # Serper.dev API integration
│ │ └── http-transport-service.ts # HTTP transport service
│ ├── types/
│ │ ├── serper-types.ts # Serper API TypeScript interfaces
│ │ ├── serper-errors.ts # Custom error classes
│ │ ├── resource-types.ts # MCP resource TypeScript interfaces
│ │ ├── validation-types.ts # Parameter validation types
│ │ └── http-transport-types.ts # HTTP transport TypeScript interfaces
│ ├── config/
│ │ └── environment-config.ts # Environment configuration parsing
│ ├── resources/
│ │ └── prompt-template-content.ts # Prompt template resource content
│ └── utils/
│ ├── logger.ts # Winston logging configuration
│ └── parameter-validator.ts # Input parameter validation
├── __tests__/
│ ├── serper-service.test.ts # SerperService unit tests
│ ├── mcp-tool-integration.test.ts # MCP tool integration tests
│ ├── index.test.ts # Main server functionality tests
│ ├── parameter-validator.test.ts # Parameter validation tests
│ ├── prompt-template-resource.test.ts # Resource content tests
│ └── get-quote-enhanced.test.ts # Enhanced tool integration tests
├── dist/ # Compiled JavaScript (after build)
├── coverage/ # Test coverage reports
├── docs/ # Project documentation
│ ├── decisions/ # Architecture Decision Records
│ ├── guidelines/ # Development guidelines
│ ├── plans/ # Implementation plans
│ └── tasks/ # Detailed task specifications
├── combined.log # Winston log file (all entries)
├── errors.log # Winston log file (errors only)
├── package.json # Dependencies and scripts
├── tsconfig.json # TypeScript configuration
├── jest.config.js # Jest test configuration
├── .eslintrc.js # ESLint configuration
├── .prettierrc # Prettier configuration
└── README.md # This file
This MCP server follows a monolithic TypeScript architecture as outlined in the project guidelines. The server:
McpServer instance with name and versionserver.registerTool()StdioServerTransport for communicationTo add a new tool:
server.registerTool()Example:
server.registerTool(
"new_tool",
{
title: "New Tool",
description: "Description of the new tool",
inputSchema: {
param1: z.string(),
param2: z.number().optional(),
},
},
async ({ param1, param2 }) => {
// Tool implementation
return {
content: [
{
type: "text",
text: `Result: ${param1}`,
},
],
};
}
);
To access MCP resources in your applications:
// List all available resources
const resources = await client.listResources();
console.log("Available resources:", resources);
// Read the prompt template resource
const promptTemplate = await client.readResource({
uri: "prompt-template://quote-request",
});
// Parse the JSON content
const templateData = JSON.parse(promptTemplate.contents[0].text);
console.log("Template parameters:", templateData.parameters);
This is Step 04 of the MCP Quotes Server implementation. The current version provides:
get_quote tool registration and discoveryFuture steps will include:
MIT License - see LICENSE file for details.
FAQs
A Model Context Protocol (MCP) server that provides quotes based on user requests
We found that @rhofkens/mcp-quotes-server demonstrated a healthy version release cadence and project activity because the last version was released less than a year ago. It has 1 open source maintainer collaborating on the project.
Did you know?
Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.
Company News
Socket won two 2026 Reppy Awards from RepVue, ranking in the top 5% of all sales orgs. AE Alexandra Lister shares what it's like to grow a sales career here.
Security News
NIST will stop enriching most CVEs under a new risk-based model, narrowing the NVD's scope as vulnerability submissions continue to surge.
Company News
/Security News
Socket is an initial recipient of OpenAI's Cybersecurity Grant Program, which commits $10M in API credits to defenders securing open source software.