Skip to main content
Glama
ascii-art-mcp

ascii-art-mcp

by theduodecim

ascii-art-mcp

Ascii Art MCP server

ascii-art-mcp is a Model Context Protocol (MCP) server built with Node.js and TypeScript that exposes tools for retrieving ASCII and Unicode art from a local database.

The server communicates using stdio transport, making it compatible with MCP clients such as:

  • Claude Desktop

  • Cursor

  • LM Studio

  • Open WebUI

  • Other MCP-compatible environments

https://theduodecim.github.io/ascii-art-mcp/

โ–ถ Run this MCP

Just drop this link into any MCP-compatible AI chat:

https://github.com/theduodecim/ascii-art-mcp/tree/main

"Run this MCP"

The AI will clone the repo, build it, and run it automatically. No setup needed on your end.


๐Ÿ“ฆ Installation

The package is available on npm:

https://www.npmjs.com/package/ascii-art-mcp

Install locally:

npm install ascii-art-mcp

Or run directly:

npx ascii-art-mcp

๐ŸŒ MCP Registry

This server is also published in the official Model Context Protocol Registry:

https://registry.modelcontextprotocol.io/?q=ascii-art

Server name:

io.github.theduodecim/ascii-art

This allows MCP-compatible tools to discover and install it automatically.


โš™๏ธ Requirements

  • Node.js 20+

  • npm


๐Ÿš€ Running the server manually

Development mode:

npm run dev

Build + production run:

npm run build
npm start

The server uses stdio transport and loads its data from:

db.json

located in the repository root.


๐Ÿงฐ Available MCP Tools

Related MCP server: Ascii Art AI MCP

get_ascii_art

Finds an art entry by exact nombre or by an exact value in aliases.

Input

Field

Type

Required

query

string

yes

Output

Returns the entry's art field as plain text.


search_ascii

Searches entries by categoria, tags, or both.

Input

Field

Type

Required

categoria

string

optional

tag

string

optional

At least one filter is required.

Output

Returns matching entries' art fields combined as text output.


random_ascii

Returns a random entry from the database.

Input

Field

Type

Required

tipo

ascii | unicode

required

Output

Returns the selected entry's art field as plain text.


list_categories

Lists all unique categories present in the database.

Input

None

Output

Category names as newline-separated text.


๐Ÿ—‚ Data Model

Entries in db.json follow the AsciiArtEntry TypeScript interface:

src/types/asciiArt.ts

Each entry contains metadata such as:

  • name

  • category

  • tags

  • aliases

  • art content


๐Ÿงช Testing the MCP Server

A simple integration test was used to verify MCP communication using JSON-RPC over stdio.

Example test script (test.mjs):

import { spawn } from "child_process";

const proc = spawn("node", ["dist/server.js"], {
  stdio: ["pipe", "pipe", "pipe"]
});

proc.stderr.on("data", (d) => {
  console.log("LOG:", d.toString());
});

proc.stdout.on("data", (d) => {
  console.log("SERVER:", d.toString());
});

function send(msg) {
  const json = JSON.stringify(msg);
  const payload = `Content-Length: ${Buffer.byteLength(json)}\r\n\r\n${json}\r\n`;

  console.log("\nSENDING:\n", json, "\n");

  proc.stdin.write(payload);
}

setTimeout(() => {
  send({
    jsonrpc: "2.0",
    id: 1,
    method: "initialize",
    params: {
      protocolVersion: "2024-11-05",
      capabilities: {},
      clientInfo: {
        name: "tester",
        version: "1.0"
      }
    }
  });
}, 500);

setTimeout(() => {
  send({
    jsonrpc: "2.0",
    method: "initialized",
    params: {}
  });
}, 1000);

setTimeout(() => {
  send({
    jsonrpc: "2.0",
    id: 2,
    method: "tools/list"
  });
}, 1500);

setTimeout(() => {
  proc.kill();
  console.log("TEST FINISHED");
}, 4000);

๐Ÿง  Architecture

src/
  server.ts
  tools/
  types/

dist/

db.json
  • TypeScript MCP server

  • JSON database (db.json)

  • Zod validation for tool inputs

  • stdio transport


๐ŸŽฏ Purpose

This project demonstrates how to build a simple MCP tool server that:

  • runs locally

  • requires no API keys

  • exposes structured tools

  • serves static data through MCP


๐Ÿ“œ License

MIT

Available Tools

4 tools
get_ascii_artA

Search an ASCII/Unicode art entry by nombre or aliases and return the art text.

Inputs: query (required).

list_categoriesA

List all unique categories available in the database.

Inputs: no named parameters.

random_asciiA

Return a random ASCII/Unicode art entry, optionally filtered by tipo.

Inputs: tipo.

search_asciiA

Search entries by categoria or tags and return matching art texts.

Inputs: tag, categoria.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelogโ€ฆ

    TDQS

    A3.9/5.0

    Scored across 4 tools

    Disambiguation4/5

    get_ascii_art and search_ascii both return matching art texts, which could cause some confusion, but they are distinguished by query type (name/aliases vs. category/tags). random_ascii and list_categories are clearly distinct.

    Naming Consistency4/5

    Three tools follow a clear verb_noun pattern (get_ascii_art, search_ascii, list_categories), and random_ascii is still readable and consistent in snake_case despite lacking a typical verb prefix.

    Tool Count5/5

    With only 4 tools, the server is tightly scoped to ASCII art retrieval and discovery. Every tool serves a useful purpose and the count feels appropriate for the niche domain.

    Completeness5/5

    The server covers the core read-only workflows: finding by name, browsing by category/tag, getting random art, and listing available categories. There are no obvious missing operations for an ASCII art lookup service.

    Maintenance

    ActivityMaintained
    ResponsivenessOutdated data

    Related MCP Connectors

    Related MCP Servers