ascii-art-mcp
Exposes local ASCII/Unicode art through MCP tools.
get_ascii_art: retrieve an art entry by exact name or alias.search_ascii: find matching art by category, tag, or both and return combined text.random_ascii: return a random art entry, optionally filtered as ascii or unicode.list_categories: list all unique categories in the database.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@ascii-art-mcp Search for ASCII art tagged cat"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
ascii-art-mcp
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-mcpOr 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-artThis allows MCP-compatible tools to discover and install it automatically.
โ๏ธ Requirements
Node.js 20+
npm
๐ Running the server manually
Development mode:
npm run devBuild + production run:
npm run build
npm startThe server uses stdio transport and loads its data from:
db.jsonlocated 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.tsEach 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.jsonTypeScript 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 toolsget_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
Scored across 4 tools
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.
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.
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.
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
Related MCP Connectors
MCP server for accessing curated awesome list documentation
An MCP server that provides tools to discover and retrieve podcast episodes transcripts.
MCP registry & directory: search, find & install 31k+ MCP servers & tools. Catalog and marketplace.
Related MCP Servers
- MIT
- AlicenseNot gradedqualityCmaintenanceAscii Art AI - MCP server providing AI-powered tools and automation by MEOK AI Labs9 npm64 PyPIMIT
- AlicenseNot gradedqualityDmaintenanceA comprehensive MCP server for querying the MusicBrainz database, providing tools to search for artists, releases, recordings, and browse music metadata.4MIT
- FlicenseNot gradedqualityDmaintenanceAn MCP server that enables AI agents to create beautiful ASCII diagrams using Unicode box-drawing characters, with support for stateful canvas operations, multiple shape types, and style customization.2-